Forem: Blues

Sending and Receiving Binary Files with the Notecard and Notehub

Rob Lauer — Tue, 28 Nov 2023 16:13:33 +0000

The Notecard was originally designed as a low-bandwidth and low-power device that effortlessly syncs user-defined JSON payloads (e.g. key/value pairs of strings, booleans, and integers) with any cloud endpoint. However, one of the most-repeated requests we heard from customers is the ability to also sync larger payloads of binary data (most often in the form of images).

With the release of the Notecard developer firmware release v5.3.1, this is now possible using the new card.binary APIs. Even better, our firmware libraries for Arduino/C and Python abstract away the complexity of the card.binary requests for you.

In this article, I'm going to show an example in Arduino/C of how to:

Request a JPEG image from a cloud endpoint.
Write that JPEG image to a Micro SD card.
Send that same JPEG image back to a different cloud endpoint.

Hardware Setup

For this example, I'm using the following hardware:

Blues Swan (STM32L4-based host MCU)
STLINK Programmer/Debugger (optional, but makes working with STM32-based MCUs more pleasant)
Blues Notecard Cellular (any Notecard will do!)
Blues Notecarrier A (a development board for interfacing with the Notecard)
Adafruit's Micro SD breakout board
2 x LiPo batteries

Wiring the Micro SD Breakout to the Swan

First, you'll want to wire up the Swan to the Micro SD breakout. The following table outlines the wiring needed to connect the two:

SD Breakout	Blues Swan
GND	GND
3v	3V3
CLK	CK
DO	MI
DI	MO
CS	A3

Attaching the Notecarrier to the Swan

Next, attach the Notecarrier A to the Swan via a Qwiic cable. Note that the Swan and Notecarrier A also need to be powered separately either over Micro USB or an attached LiPo battery, as Qwiic doesn't deliver enough power to boot the Notecard.

Your hardware should look something like the following (with or without the STLINK debugger of course):

Format the Micro SD Card

If you haven't already, be sure the Micro SD card you're using is already formatted as either FAT16 (if < 2GB) or FAT32. If not, you can use a USB SD card reader with your PC to format it using the SD Association's Memory Card Formatter (available on macOS/Win and Linux).

Now it's time to write the sketch!

Looking for a shortcut? Check out this gist to see the completed sketch.

Setup the Notecard and SD Card Breakout

Include the necessary libraries in your project, including note-arduino for the Notecard and the Arduino SD Library for the Micro SD breakout board. Also, add the variables needed to interface with the components:

#include <Arduino.h>
#include <Wire.h>
#include <Notecard.h>
#include <SD.h>

Notecard notecard;
File myImageFile;
Sd2Card card;
SdVolume volume;
SdFile root;
const int chipSelect = A3;
HardwareSerial stlinkSerial(PIN_VCP_RX, PIN_VCP_TX);
#define usbSerial Serial

int ledPin = LED_BUILTIN; // references onboard LED on Swan

Initialize the Notecard and Micro SD Breakout

Most everything else occurs in the setup() method.

Set the pinMode of the Swan's onboard LED to OUTPUT so we can blink it later. Also, if you're using the STLINK, be sure to initialize it so you can see output in the serial monitor.

pinMode(ledPin, OUTPUT);

Wire.begin();

// if using STLINK debugger
stlinkSerial.begin(115200);
const size_t usb_timeout_ms = 5000;
for (const size_t start_ms = millis(); !stlinkSerial && (millis() - start_ms) < usb_timeout_ms;)
  ;

notecard.setDebugOutputStream(stlinkSerial);

Next, initialize the Notecard, link your Notecard to your project in Notehub via the product key, and reset the Notecard's binary storage area to make sure we have the space required to save an image.

If you haven't set up a Notehub account yet, you should, because it's free to use (up to 5,000 events routed per month!) and only takes an email address.

notecard.begin();

J *req = notecard.newRequest("hub.set");
JAddStringToObject(req, "product", "com.your.project:uid");
JAddStringToObject(req, "mode", "continuous");
JAddBoolToObject(req, "sync", true);
notecard.sendRequestWithRetry(req, 5);

// wait until we are connected to notehub
// this is REQUIRED when sending binary data!
bool connected = false;
while (!connected)
{
  req = notecard.newRequest("hub.status");
  J *rsp = notecard.requestAndResponse(req);
  connected = JGetBool(rsp, "connected");
  delay(2000);
}

// Reset the Notecard's binary storage area, so we can start fresh
NoteBinaryStoreReset();

Next, initialize the connected Micro SD card:

// init the SD card for usage
stlinkSerial.println("Initializing SD card...");

if (!card.init(SPI_HALF_SPEED, chipSelect))
{
  stlinkSerial.println("SD card initialization failed!");
  while (1);
}

// try to open the 'volume'/'partition' - it should be FAT16 or FAT32
if (!volume.init(card))
{
  stlinkSerial.println("Could not find FAT16/FAT32 partition.\nMake sure you've formatted the card");
  while (1);
}

That's it for our initialization tasks. Next up, it's time to request an image file!

Request an Image from the Cloud

For security reasons, the Notecard cannot connect directly to any arbitrary cloud endpoint. It doesn't have a public IP address, nor would you want it to have one. This is where Notehub comes into play, as the Notecard and Notehub work together to form a secure "off the public Internet" link.

To request a binary file from a cloud end point, we'll have to set up a Notehub Route.

Routes allow you to send data from Notehub to a public cloud like AWS, Azure, or Google Cloud, a messaging platform like MQTT, or a custom HTTP/HTTPS endpoint. Routes are defined in a Notehub for a single project, and can target any number of Notecard fleets and devices.

Let's say you have a cloud endpoint that will return binary data (i.e. an image file). Make sure you have the URL of the endpoint available.

In Notehub, navigate to the Routes menu option, and create a new Proxy for Notecard Web Requests route:

Supply an arbitrary Route Name and the URL that Notehub should use to fetch the image with a GET. Also, you'll need to add an arbitrary Alias string, which is how you'll reference this Route in the sketch below.

That's it!

Back in your sketch, you'll use the web.get API to call the newly-created Notehub Route (called GetImage) and store whatever binary data is returned in flash on the Notecard:

J *req = NoteNewRequest("web.get"))
JAddStringToObject(req, "route", "GetImage");
JAddBoolToObject(req, "binary", true);

if (!NoteRequest(req))
{
  notecard.logDebug("Error receiving image\n");
}

uint32_t data_len = 0;
NoteBinaryStoreDecodedLength(&data_len);

uint32_t rx_buffer_len = NoteBinaryCodecMaxEncodedLength(data_len);
uint8_t *rx_buffer = (uint8_t *)malloc(rx_buffer_len);

// Receive the data
NoteBinaryStoreReceive(reinterpret_cast<uint8_t *>(rx_buffer), rx_buffer_len, 0, data_len);
notecard.logDebugf("\n[INFO] Received %d bytes.\n", data_len);

Save the Image to the Micro SD Card

Next, you'll want to write the saved binary buffer from the Notecard to the Micro SD card, using methods provided by the Arduino library:

// save the buffer to the specified file name on the SD card
SD.begin(chipSelect);
SD.remove("logo.jpg"); // remove the file if it already exists
myImageFile = SD.open("logo.jpg", FILE_WRITE);

if (myImageFile)
{
  myImageFile.write(rx_buffer, data_len);
  myImageFile.close();
  stlinkSerial.println("Completed writing the file!\n");
}

You can now pull the SD card out of the breakout board and pop it into your PC to see if the file was saved correctly (in my case I downloaded the Blues logo of course).

Yes you'll just have to take my word that it worked!

Send the Image Back to a Cloud Endpoint

So far you've downloaded a file and saved it to SD, but what about uploading it back to another cloud endpoint?

Welcome to the magic of Notehub Routes (yes, they work both ways)!

Back in Notehub, again navigate to the Routes menu option, and create a new General HTTP/HTTPS Request/Response route (this is different than the Proxy for Notecard Web Requests route type, as this time we will be generating a payload locally using Notes to send data from the Notecard to Notehub).

Provide an arbitrary Route Name and the remote URL that Notehub will use to POST the binary data. In my case, I used the venerable webhook.site for an easy way to inspect outbound data to the cloud.

Continue to the Filters section and be sure that you are only routing data from the Notecard that appears in the binary.qo Notefile (this is the name of the Notefile that will contain the binary payload).

All set? Back to your sketch!

const uint32_t notecard_binary_area_offset = 0;
NoteBinaryStoreTransmit(reinterpret_cast<uint8_t *>(rx_buffer), data_len, sizeof(rx_buffer), notecard_binary_area_offset);
notecard.logDebugf("\n[INFO] Transmitted %d bytes.\n", data_len);

// Send the binary data to Notehub
if (J *req = notecard.newRequest("note.add"))
{
  JAddStringToObject(req, "file", "binary.qo");
  JAddBoolToObject(req, "binary", true);
  JAddBoolToObject(req, "live", true);
  notecard.sendRequest(req);
}

// Free the receive buffer
free(rx_buffer);

stlinkSerial.println("Completed sending the file!\n");

Believe it or not, that's all that is required. In this code block, you are using the saved binary buffer that's already stored in flash on the Notecard (the image file just downloaded previously) and sending it to Notehub using the note.add API. Note that you're also supplying the binary:true and live:true arguments of note.add in order to pass the binary data from the Notecard to Notehub!

Viewing the Binary Payload in the Cloud

Depending on how you set up the Notehub Route that POSTs data, you should be able to see the binary data delivered. As mentioned earlier, I used webhook.site which lets me inspect delivered payloads. Here is a snippet of the binary file I delivered:

Wrapping Up with a Blink and a Loop

Since I like to get some visual indication that my sketch has run to completion, in the loop() method, I simply flash the Swan's onboard LED on and off:

void loop()
{
  // Finally, blink the Swan's LED when done!
  digitalWrite(ledPin, HIGH);
  delay(1000);
  digitalWrite(ledPin, LOW);
  delay(1000);
}

For a quick view of the full Arduino sketch, consult this gist.

Next Steps

What I've shown here is a relatively simple way of downloading and uploading binary data with the Notecard. More likely you may be dealing with larger binary files that have to be processed in "chunks" that the Notecard can handle. Be sure to consult our additional example Arduino sketch that shows how to accomplish this more advanced scenario.

If you haven't already, grab your own Blues Starter Kit and see how easy it really can be to sync data from a physical device to the cloud (over Cellular, Wi-Fi, or LoRa!).

Happy Hacking! 💙

The Easiest Way to Upgrade Raspberry Pi OS from Bullseye to Bookworm

Rob Lauer — Tue, 07 Nov 2023 17:26:45 +0000

If you're like me, when a new version of an OS comes out (I don't care of it's macOS, Windows, or Raspberry Pi OS) I feel an irrational need to install it. I'm also exceptionally lazy, so I usually opt for the upgrade path versus a clean install.

Today I want to take a look at how you can update a Raspberry Pi (or compatible single board computer) to the newly released "Bookworm" version of Raspberry Pi OS.

Let me be crystal clear: This is an unsupported upgrade path that is not endorsed by the Raspberry Pi Foundation.

But I also like to live dangerously.

Before continuing, I'm sure at least some of you are wondering: What exactly is Bookworm?

What is Bookworm?

Bookworm is the codename for a new version of Raspberry Pi OS. Based on Debian GNU/Linux 12, Bookworm is a significant new release for Raspberry Pi enthusiasts.

Arguably the three most important updates in Bookworm are:

A switch from the X11 Windowing System to Wayland, which improves security and performance (and includes some pleasing desktop UI updates).
Adopting PipeWire as the default audio backend (replacing PulseAudio).
Use of NetworkManager as the default network suite (replacing dhcpcd).

Bullseye to Bookworm Upgrade Options

The good news is there are multiple upgrade options from Bullseye to Bookworm.

The bad news is there are multiple upgrade options from Bullseye to Bookworm.

Easy Upgrade Path
Better Upgrade Path
Best "Upgrade" Path (the officially recommended path, but that's not why you're here)

WARNING: Regardless of the path you take, be sure to make a full backup of the SD card you're using for your current Raspberry Pi installation. Yes, just in case.

The Easy Upgrade Path from Bullseye to Bookworm

Sorry, one more warning:

WARNING: These instructions are only valid for upgrading from Bullseye. If you are currently running Buster, you'll have to install Bullseye first (but at that point, seriously, just install a fresh version of Bookworm and ignore the rest of this blog post, except for the ending).

Ready? Backup finished? Anxious to get started? Let's begin!

Perform a full upgrade of your existing Bullseye installation. Open a Terminal and enter these commands, sequentially:

   sudo apt update
   sudo apt full-upgrade
   sudo reboot

After rebooting, enter the following command to edit sources.list, which is how your Pi references the archives for the Debian repositories:

   sudo nano /etc/apt/sources.list

Update the first line, replacing bullseye with bookworm and adding non-free-firmware to the end of the line. Your sources.list file should end up looking something like this:

   deb http://raspbian.raspberrypi.org/raspbian/ bookworm main contrib non-free rpi non-free-firmware

Type ctrl-x to exit nano, making sure you save the file on exit. Next, you need to open raspi.list (to update the Debian Bookworm base) with this command:

   sudo nano /etc/apt/sources.list.d/raspi.list

In this file, you only need to change bullseye to bookworm. Again, hit ctrl-x, save your changes, and exit.
Perform another full upgrade, but this time sourcing from the Bookworm repositories!

   sudo apt update
   sudo apt full-upgrade
   sudo reboot

And now you wait. And wait some more.

After this final reboot, confirm that you're now running an almost complete version of Bookworm with this command:

   cat /etc/os-release

Success! 🥳

However, while it looks and feels like this is a full upgrade to Bookworm, some smarter people than I have pointed out that changes like PipeWire and NetworkManager may not be properly configured via this route. That's what the "Better Way" is for:

A Better Way to Upgrade to Bookworm

Yes, there is a better way. It's not for the faint of heart though.

A brave soul on GitHub is actively updating a series of commands for a full in-place upgrade from Bullseye to Bookworm in this gist.

As of the publishing of this blog post in November 2023, here is the full list of commands. Godspeed.

### WARNING: READ CAREFULLY BEFORE ATTEMPTING ###
#
# Credit to anfractuosity and fgimenezm for figuring out additional details for kernels
#

# Make sure everything is up-to-date
sudo apt-get update && sudo apt-get dist-upgrade

# Point to bookworm repos instead
sudo sed -i -e 's/bullseye/bookworm/g' /etc/apt/sources.list
sudo sed -i -e 's/bullseye/bookworm/g' /etc/apt/sources.list.d/raspi.list

# Do actual update
sudo apt update && sudo apt -y full-upgrade && sudo apt -y clean && sudo apt -y autoremove

# Reboot
sudo reboot

# Remove old config files after doing sanity checks
sudo apt purge ?config-files

### Switch to the new kernels ###
# Prep
sudo dpkg --purge --force-depends raspberrypi-kernel raspberrypi-bootloader
sudo umount /boot
sudo fsck -y /boot
sudo mkdir /boot/firmware
sudo sed -i.bak -e "s#boot#boot/firmware#" /etc/fstab
sudo systemctl daemon-reload
sudo mount /boot/firmware
sudo apt install raspi-firmware

# Actually install the kernels. Make sure you pick the right version for your Pi
# sudo apt install linux-image-rpi-v8 linux-headers-rpi-v8      # 64bit
# sudo apt install linux-image-rpi-v7l linux-headers-rpi-v7l    # 32bit
# sudo apt install linux-image-rpi-v6 linux-headers-rpi-v6      

# Append auto_initramfs=1 to the bottom of file where it says [all]
sudo sed -i.bak '$ a\auto_initramfs=1' /boot/firmware/config.txt 

# Reboot
sudo reboot

# Verify using "uname -a" (correct as of 10/2023)
# Old kernel
# Linux raspberrypi 6.1.21-v8+ #1642 SMP PREEMPT Mon Apr  3 17:24:16 BST 2023 aarch64 GNU/Linux
# New kernel
# Linux raspberrypi 6.1.0-rpi4-rpi-v8 #1 SMP PREEMPT Debian 1:6.1.54-1+rpt2 (2023-10-05) aarch64 GNU/Linux

# If you are not converted to using NetworkManager, you might lose networking upon reboot. 
# Check the ARP table to see what the new DHCP assigned IP address is. You may have to manually set the IP address again
# Thanks to solsticedhiver for identifying this
#
# Switch to NetworkManager from dhcpcd
sudo systemctl enable --now NetworkManager
sudo systemctl disable --now dhcpcd
#
# Set up static IP. Adjust as necessary 
sudo nmcli -p connection show 
sudo nmcli -p connection show "Wired connection 1"
sudo nmcli con mod "Wired connection 1" ipv4.method manual ipv4.addresses 192.168.1.5/24 ipv4.gateway 192.168.1.1

# Reboot
sudo reboot

#
# Bonus steps
#
# Install btop
sudo apt-get install btop
#
# Update /etc/ssh/sshd_config for up to date, secure by default config. Use ssh-audit to verify
KexAlgorithms sntrup761x25519-sha512@openssh.com,curve25519-sha256,curve25519-sha256@libssh.org
HostKeyAlgorithms ssh-ed25519-cert-v01@openssh.com,ssh-ed25519
Ciphers chacha20-poly1305@openssh.com
MACs hmac-sha2-512-etm@openssh.com,hmac-sha2-256-etm@openssh.com

The Best Way to "Upgrade" to Bookworm

After all we just went through, do you really want to know what I think is the best way to upgrade to Bookworm?

Well, it's quite simple and foolproof:

Backup all of the directories and files you want to keep from your Pi.
Download and install the Raspberry Pi Imager.
Format an SD card and install a fresh copy of Bookworm.
Copy your files back to the Pi.
Success! 🥳

Easy Cellular, LoRa, and Wi-Fi on the Pi

Now that you're done, if you're in the market for a new way to add swappable Cellular, LoRa, and Wi-Fi to your Raspberry Pi, take a look at the Blues Notecard and the Blues Notecarrier Pi HAT.

The cellular-based Notecards provide 500MB of prepaid data and 10 years of global cellular service. These are commonly used in edge deployments of Raspberry Pis that don't have access to reliable Wi-Fi connectivity.

Learn more about adding low-bandwidth cellular to the Raspberry Pi in many of these project tutorials on Hackster.

Happy Hacking! 💙

Read and Write Images and Text Files with a Micro SD Card and Arduino

Rob Lauer — Tue, 24 Oct 2023 17:01:15 +0000

We've all been there. Well, at least I've certainly been there:

I want to perform what I assume to be a simple task with C (Arduino): "I just want to read and write some data to a Micro SD card! This can't be that difficult can it!?"

Five searches deep on Google, I realize there are far too many ways to skin this particular cat. Different components, different libraries, and even different libraries for the same components.

Time to take a deep breath and channel my internal Bob Ross...

This article is meant cut out the extraneous info and provide a guide for what I consider to be the easiest way to use a Micro SD card with Arduino to read/write text and image files.

In this mini-project, I'm using the following hardware:

Hardware Wiring

Since you're are only wiring a couple of components together this is a relatively simple step, but it's important to get the wiring correct:

SD Breakout	Blues Swan
GND	GND
3v	3V3
CLK	CK
DO	MI
DI	MO
CS	A3

Your wiring should end up looking like something like this:

Prepping the Micro SD Card

You'll want to make sure the Micro SD card is formatted as either FAT16 (if <= 2GB) or FAT32. If not, simply get ahold of a USB SD card reader and use your PC to format it using the SD Association's Memory Card Formatter (macOS/Win and Linux).

Slide that Micro SD card back in the breakout board and we are ready to write some code.

Arduino Micro SD Breakout Library

One of the reasons I chose Adafruit's Micro SD breakout board (aside from the generally high quality of their hardware) is because they offer well-supported and well-documented libraries. This one is no exception.

Consult this GitHub repository for the latest version of the Arduino SD Library.

Let's look at how we might perform some typical file-based tasks with an SD card, in particular:

Writing and reading text files.
Writing and reading images (PNGs).

Writing a Text File

Using a Micro SD card as a data logger is very common in our industry. They are inexpensive and a relatively stable medium.

You didn't ask, but if you want my opinion, your data should only be saved to SD as a backup. I'll always recommend you sync data with the cloud using the Cellular, Wi-Fi, or LoRa-based Notecard, but I digress...

The following sketch will initialize the SD card breakout board and write a string to a text file:

#include <SD.h>

File textFile;
Sd2Card card;
SdVolume volume;
const int chipSelect = A3;

void setup()
{
  Serial.begin(9600);

  Serial.println("Starting SD card init...");

  if (!card.init(SPI_HALF_SPEED, chipSelect))
  {
    Serial.println("SD card initialization failed!");
    while (1)
      ;
  }

  // try to open the 'volume'/'partition' - it should be FAT16 or FAT32
  if (!volume.init(card))
  {
    Serial.println("Could not find FAT16/FAT32 partition.");
    while (1)
      ;
  }

  SD.begin(chipSelect);

  Serial.println("SD initialization complete!");

  // open a new file for writing
  textFile = SD.open("hello.txt", FILE_WRITE);

  if (textFile) {
    textFile.println("Hello World!");
    textFile.close();
    Serial.println("Completed writing a text file!");
  }
}

void loop()
{
}

Note that there are a few things to be aware of when working with files:

You'll want to keep filenames short and use the 8.3 format (e.g. MYFILE.TXT).
Filenames are NOT case sensitive, so in code, myfile.txt == MYFILE.TXT.
Always close() your files when done to make sure any pending writes are properly saved.

Reading from a Text File

Now that you've written a simple text file to a Micro SD card, let's see how easy it can be to read data from an existing file (specifically the hello.txt file we just created).

Add the following code snippet after the file is created:

// open the existing file for reading
textFile = SD.open("hello.txt");
if (textFile)
{
  Serial.println("here's the data in hello.txt:");

  // read until there's nothing else in it:
  while (textFile.available())
  {
    Serial.write(textFile.read());
  }
  // close the file:
  textFile.close();
}

If you're using the serial monitor to see the output, you may be surprised to see "Hello World!" repeated many times. What's up with that?

Starting SD card init...
SD initialization complete!
Completed writing a text file!
here's the data in hello.txt:
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!

This is because writing to an existing file appends data by default and doesn't overwrite existing data. In my case, I had clearly tested the write sequence a handful of times before I read the data out.

To fix this, you can always remove() the file first:

SD.remove("hello.txt");

Other Useful Functions When Working with Files on SD

Before writing to a file, you might want to see if it already exists by using the SD.exists("thefile.txt") function.

Create directories and subdirectories with the SD.mkdir("/newdir") function.

Use the aforementioned SD.remove("thefile.txt") function to delete files.

Be sure to consult Adafruit's full tutorial for additional information on using this breakout board with a Micro SD card.

Working with Images

Let's switch gears and ramp up the complexity a little bit by writing and reading images to/from the Micro SD card.

As with every complex Arduino task, we first need to ask: "Is there library for this?". The answer is almost always "yes", and this time is no exception.

When working with image files on host microcontrollers with a relatively small amount of memory and processing power, we usually want to try to work with small files. Bitmap (.bmp) is a good format for lossless, but simple, images. Modern hosts are more often dealing with higher fidelity images that can't reasonably be sent uncompressed over the wire. This is where the usage of a format like JPEG or PNG come in handy.

Choosing the optimal type of compression to use will depend on the image itself (e.g. photos usually compress best with JPEG while drawings/line art are best compressed with PNG or WEBP).

Example of thermal camera images saved as BMP, PNG, and JPG:

And yes there are libraries for these options as well! JPGenc and JPGdec for encoding/decoding JPG images, and PNGenc and PNGdec for encoding/decoding PNGs.

Looking for a functional example of image compression in action? Check out this project on Hackster that uses a thermal camera to capture images, show them on a TFT display, and save them to a Micro SD card.

Writing an Image to a Micro SD Card

While this is a bit of a contrived example, let's strip down a code example to its bare minimum and look at how you might draw a basic image and save it to the SD card.

The following sketch creates a 128x128 image with a green border and green "x" going through it, like so, using the PNGenc library:

#include <PNGenc.h>
#include <SD.h>

PNG png;
File myPNG;
Sd2Card card;
SdVolume volume;
const int chipSelect = A3;

void *myOpen(const char *filename)
{
    Serial.printf("Attempting to open %s\n", filename);
    myPNG = SD.open(filename, O_READ | O_WRITE | O_CREAT);
    return &myPNG;
}
void myClose(PNGFILE *handle)
{
    File *f = (File *)handle->fHandle;
    f->close();
}
int32_t myRead(PNGFILE *handle, uint8_t *buffer, int32_t length)
{
    File *f = (File *)handle->fHandle;
    return f->read(buffer, length);
}
int32_t myWrite(PNGFILE *handle, uint8_t *buffer, int32_t length)
{
    File *f = (File *)handle->fHandle;
    return f->write(buffer, length);
}
int32_t mySeek(PNGFILE *handle, int32_t position)
{
    File *f = (File *)handle->fHandle;
    return f->seek(position);
}

#define WIDTH 128
#define HEIGHT 128

uint8_t ucPal[768] = {0, 0, 0, 0, 255, 0}; // black, green
uint8_t ucAlphaPal[256] = {0, 255};        // first color (black) is fully transparent

void setup()
{
    int rc, iDataSize, x, y;
    uint8_t ucLine[WIDTH];
    long l;

    Serial.begin(115200);

    Serial.println("Starting SD card init...");

    if (!card.init(SPI_HALF_SPEED, chipSelect))
    {
        Serial.println("SD card initialization failed!");
        while (1)
            ;
    }

    // try to open the 'volume'/'partition' - it should be FAT16 or FAT32
    if (!volume.init(card))
    {
        Serial.println("Could not find FAT16/FAT32 partition.");
        while (1)
            ;
    }

    SD.begin(chipSelect);

    Serial.println("SD initialization complete!");

    l = micros();

    rc = png.open("/testimg.png", myOpen, myClose, myRead, myWrite, mySeek);

    if (rc == PNG_SUCCESS)
    {
        rc = png.encodeBegin(WIDTH, HEIGHT, PNG_PIXEL_INDEXED, 8, ucPal, 3);
        png.setAlphaPalette(ucAlphaPal);
        if (rc == PNG_SUCCESS)
        {
            for (int y = 0; y < HEIGHT && rc == PNG_SUCCESS; y++)
            {
                // prepare a line of image to create a red box with an x on a transparent background
                if (y == 0 || y == HEIGHT - 1)
                {
                    memset(ucLine, 1, WIDTH); // top+bottom green lines
                }
                else
                {
                    memset(ucLine, 0, WIDTH);
                    ucLine[0] = ucLine[WIDTH - 1] = 1;     // left/right border
                    ucLine[y] = ucLine[WIDTH - 1 - y] = 1; // X in the middle
                }
                rc = png.addLine(ucLine);
            } // for y
            iDataSize = png.close();
            l = micros() - l;
            Serial.printf("%d bytes of data written to file in %d us\n", iDataSize, (int)l);
        }
    }
}

void loop()
{
}

This is a lightly-edited version of the example sketch from the PNGenc repository.

The devil is always in the details when dealing with images, as every project has differing requirements. You likely either have images pre-loaded on an SD card or you are capturing new images with a camera. If using a camera, you'll need a host MCU with enough memory to encode/compress/save the image AND you'll have to find a library specific to the camera you are using.

Reading an Image from an SD Card

Now that we can write a simple PNG image, let's see how we might read PNGs using the PNGdec library.

Your mileage may vary, but at the time of this writing, both PNGenc and PNGdec cannot be used at the same time in the same project.

The following sketch will read all PNG files from the root directory of an SD card and load them, one at a time, into memory. Again, this is not very functional because it doesn't actually "do" anything with the images, but it's a good first step:

#include <PNGdec.h>
#include <SD.h>

PNG png;
File myPNG;
Sd2Card card;
SdVolume volume;
const int chipSelect = A3;

void setup()
{

    Serial.begin(115200);

    Serial.println("Starting SD card init...");

    if (!card.init(SPI_HALF_SPEED, chipSelect))
    {
        Serial.println("SD card initialization failed!");
        while (1)
            ;
    }

    // try to open the 'volume'/'partition' - it should be FAT16 or FAT32
    if (!volume.init(card))
    {
        Serial.println("Could not find FAT16/FAT32 partition.");
        while (1)
            ;
    }

    SD.begin(chipSelect);

    Serial.println("SD initialization complete!");
}

void *myOpen(const char *filename, int32_t *size)
{
    Serial.printf("Attempting to open %s\n", filename);
    myPNG = SD.open(filename);
    *size = myPNG.size();
    return &myPNG;
}
void myClose(void *handle)
{
    if (myPNG)
        myPNG.close();
}
int32_t myRead(PNGFILE *handle, uint8_t *buffer, int32_t length)
{
    if (!myPNG)
        return 0;
    return myPNG.read(buffer, length);
}
int32_t mySeek(PNGFILE *handle, int32_t position)
{
    if (!myPNG)
        return 0;
    return myPNG.seek(position);
}

// Function to draw pixels to the display
void PNGDraw(PNGDRAW *pDraw)
{
    uint16_t usPixels[320];

    png.getLineAsRGB565(pDraw, usPixels, PNG_RGB565_LITTLE_ENDIAN, 0xffffffff);
}

// Main loop, scan for all .PNG files on the card and display them
void loop()
{
    int rc, filecount = 0;
    File dir = SD.open("/");
    while (true)
    {
        File entry = dir.openNextFile();
        if (!entry)
            break;
        if (entry.isDirectory() == false)
        {
            const char *name = entry.name();
            const int len = strlen(name);
            if (len > 3 && strcmp(name + len - 3, "PNG") == 0)
            {
                Serial.print("File: ");
                Serial.println(name);
                rc = png.open((const char *)name, myOpen, myClose, myRead, mySeek, PNGDraw);
                if (rc == PNG_SUCCESS)
                {
                    Serial.printf("image specs: (%d x %d), %d bpp, pixel type: %d\n", png.getWidth(), png.getHeight(), png.getBpp(), png.getPixelType());
                    rc = png.decode(NULL, 0);
                    // do something...anything..with the PNG file!
                    png.close();
                }
            }
        }
        entry.close();
    }
}

And what does the output look like in the serial monitor?

File: TESTIMG.PNG
Attempting to open TESTIMG.PNG
image specs: (128 x 128), 8 bpp, pixel type: 3

Success! 🥳

Summary

Hopefully you've seen how easy your first steps can be when using a Micro SD card to read and write images and text files with Arduino/C.

As mentioned above, every project scenario is different (whether you're just reading images pre-loaded to the SD card, creating PNGs from a thermal camera module, or most likely taking a picture with an attached camera module and storing them as JPEGs).

Including a Micro SD card as a data logger is a simple and effective way to store data (which of course you'll later end up syncing to the cloud via Cellular, Wi-Fi, or LoRa using the Notecard!).

Happy Hacking! 💙

How It's Made — Manufacturing Notecard at Scale

David Scheltema — Wed, 27 Sep 2023 16:00:00 +0000

While it is easy to get your hands on a Blues Notecard, it's not as easy to learn what it takes to manufacture one. That is... until today.

This post walks you through the factory floor as a panel of Notecards pass through each step of the manufacturing process — going from an unpopulated printed circuit board (PCB) to a working Notecard.

Before the Manufacturing Even Begins

The manufacturing process is the culmination of a huge amount of behind the scenes engineering and operational work. Before a single component is shipped to the manufacturing facility, electrical engineers must finish the PCB design and layout. This information packaged in a Gerber file format, which provides the exact design requirements for the PCB as well as the placement of the components.

Simultaneously to the work of the electrical engineers, operation engineers work with component vendors and suppliers to find the best prices, and component variants for the quantities necessary to successfully manufacture the electrical engineer's design.

It All Starts with Printed Circuit Boards

Notecard PCBs are the first component of the manufacturing process that need to be manufactured. Using a layering process of copper and FR4—a type of fire-resistant fiberglass—PCBs are built one layer at a time. Advanced PCBs like Notecard's use multiple layers of FR4 and copper to properly connect all of the components necessary to make up the final design.

Scotty from the YouTube channel Strange Parts has a great video tour of the PCB manufacturing process if you're interested in the step-by-step process.

With Notecard manufacturing a panel of eight Notecards is the smallest unit of material that goes through the line. This improves production output while reducing the time that the manufacturing line is operational.

As you can see in the unpopulated panel above, the exterior layer of the Notecard PCB consists of exposed copper pads and green areas of solder mask. Copper when heated will attract solder whereas the solder mask when heated will not.

Application of Solder Paste

The first stop on the manufacturing line is the solder paste machine. The Notecard panel is placed inside the machine and a thin metal stencil is secured over the panel.

An automated squeegee then smears a combination of solder paste and flux across the stencil depositing globs of the gooey material on the exposed copper pads. After a few passes of the squeegee, the stencil is removed and the panel is placed on a conveyer belt bound for the next step of the manufacturing line.

Optical Inspection

Before the manufacturing process goes any farther, a series of high-powered cameras inspect the dollops of solder paste and flux are correctly placed on the copper. Too much or too little solder and flux could be detrimental to the assembly process and potentially create bad solder joints between the PCB and the components.

This early inspection and anomaly detection is just one of the steps meant to ensure production efficiency and reduces costly rework later on in the manufacturing process.

Component Placement on the PCB

With fresh solder paste and flux on the PCB pads, the next step in the assembly process is component placement. It's here at the Pick-and-Place machine that automation is at its most advanced.

All the components that make up Notecard are loaded into the pick-and-place machine. Each component is packaged on a reel that loads into the pick and place machine almost like a printer cartridge to a laser printer.

The pick-and-place machine is programmed to know exactly where each component is stored on a reel as well as where each component must be placed on the PCB panel. Using a suction device on a gantry arm to lift the component and move it into position, the pick-and-place machine is able to precisely select and deposit tens of thousands of components per hour.

The speed and accuracy of these machines boggle the mind. They are simply put the backbone of the modern manufacturing line.

Soldering at Scale

With all the components placed on the globs of solder paste and flux, the only thing holding them in place is surface tension. To make a more permanent connection heat needs to be carefully applied to the panel of Notecards.

Unlike your typical handheld soldering iron where you solder one component at a time, manufacturing lines use reflow ovens to solder all of the components on one side of the PCB at once.

These high-tech ovens precisely modulate the temperature based on temperature curves input by engineers so that they heat up and cool down period is very deliberate and conforms to the temperature tolerances of the materials being reflowed.

When a reflow oven heats up, the solder paste and flux melt. The surface tension of the molten hot solder pulls the SMT component towards the copper pad on the PCB and as the oven temperatures drop, the solder cools and forms a solder joint — an electrical connection between the component and the PCB pad.

Astonishingly, reflow ovens are so precise that they are able to heat one side of a PCB and not melt the solder on the other side of the board. This allows for two-sided boards like Notecard to be reflowed in two passes — one for the top side and one for the bottom side — without any components falling off during the process.

After the solder joints are cooled, the panel of Notecards is conveyed to another automated optical inspection machine.

Automated Optical Inspection

Automated optical inspection at this point in the manufacturing line is focused on ensuring the solder joints and component placement have no defects.

As with the first round of optical inspections, it's far better to catch any problems here before the panel advances to the next stage of manufacturing.

Quality Control with a Human Touch

Quality control is the last stage of the manufacturing process where the eight Notecards are connected on one panel. Rather than rely on automation, this quality control step is performed by a manufacturing engineer.

They perform a visual inspection of all areas of the panel using large magnifying glasses as well as conduct other testing to ensure the Notecards have been properly assembled. Once approved, the panel of Notecards is ready for depanelization.

Depaneling into Single Notecards

Using an advanced router, the depaneling machine uses a bit to remove the excess FR4 material that held the eight Notecards together.

To ensure that the Notecards are not damaged during the process, the panel is loaded into a tray and a fixture is placed over the panel to guide the the router bit as the depanelization occurs.

Notecard Functional Testing

With each Notecard free from its panel and fully populated with components, it's ready for functional testing. This step ensures that the Notecard is able to power on properly and execute a series of test commands.

Once the Notecard passes the functional tests, it's off to the labeling and packaging department.

Individual Packaging and Boxing

Each Notecard is packaged individually inside a zip-locked back and placed into a large tray.

Multiple trays are stacked to snugly fit into larger shipping boxes to optimize the number of Notecards that can fit ship at a time.

Establishing a Robust MLOps Workflow for TinyML

TJ VanToll — Tue, 26 Sep 2023 17:37:10 +0000

A machine learning model is only as good as the data it’s trained on. Gathering a robust set of training data is challenging for any ML project, but it’s especially difficult in the world of TinyML, where devices are often underpowered and running in areas with limited connectivity.

Here at Blues we specializing in making connectivity easy for embedded projects, and together with our friends at Edge Impulse and Zephyr, we’ve put together a workflow that we think helps make MLOps—or the process of continuously improving an ML model—possible for tiny devices.

In this article I’m going to lay out an opinionated way to implement a robust MLOps process. We’ll start by looking at how to collect ML data from your remote devices, and then show how you can update ML models running on our devices in the field. At the end you’ll have a workflow that looks like this.

Let’s get started.

NOTE: See Optimized MLOps with Edge Impulse, Blues, and Zephyr on YouTube for a video version of this tutorial.

Collecting ML Data

For this article we’re going to assume we manage a fleet of devices tasked with monitoring industrial equipment. Each device is fitted with an accelerometer that measures machine vibrations, and runs those readings through an ML model that has been trained to detect abnormalities.

To adopt an MLOps workflow, this project needs a way to gather accelerometer samples from the field, and a way to send those samples to the cloud so that they can be used to train an updated model.

To send the data we’re going to use the Blues Notecard.

The Notecard is a system on module that makes connectivity simple for embedded projects. Specifically, the Notecard offers:

500MB of cellular connectivity
Global cellular over LTE-M, NB-IoT, or Cat-1
Secure “off the internet” communications from device-to-cloud
Low-power hardware (~8µA when idle), and power-conscious firmware
Easy embedding with onboard M.2 Key E connector or via a companion board

The Notecard is great for connectivity on remote devices as it can work in areas without Wi-Fi coverage, and can work on equipment that moves between locations or on vehicles. You can even use the Notecard for asset tracking.

To communicate with the Notecard in our project we need a few other pieces of hardware.

Setting up your hardware

The easiest way to get started with the Notecard is with a Blues Starter Kit. The Starter Kit comes with a development board (Notecarrier), as well as a Swan microcontroller that can run this project’s firmware.

NOTE: The Blues quickstart has full details on how to assemble a Blues Starter Kit.

With the Starter Kit assembled, the last thing we need is an accelerometer to use to take readings. For that accelerometer we’ll use an LIS3DH, which you can connect to the Starter Kit’s Notecarrier via a Qwiic cable.

With all hardware assembled, let’s look at the firmware we’ll use to gather the accelerometer readings.

The Firmware

This project’s firmware is responsible for gathering readings from the accelerometer, and using the Notecard to send those readings to the cloud.

For the firmware implementation we’re using Zephyr, as Zephyr is low-level enough to give us access to features like threading, while high-level enough to provide sensor APIs and other development conveniences. Plus, Zephyr firmware runs great on the STM32-based boards like the Swan, and the Notecard has a ready-to-use Zephyr SDK.

The full firmware source code for this project is available on GitHub, and I will highlight some of the most important parts here.

First, the firmware has to establish a connection between the Notecard and the Notecard’s backing cloud service, Notehub. It does so by performing a hub.set request on the Notecard, and sending a ProductUID that tells what project to associate this Notecard with.

J *req = NoteNewRequest("hub.set");
JAddStringToObject(req, "product", "com.your-company:your-product-name");
JAddStringToObject(req, "mode", "continuous");
JAddStringToObject(req, "sn", "your-device-name");
NoteRequest(req);

A couple of notes on the code above:

All of the Notecard’s API use JSON. The Notecard’s C SDK includes a number of helper functions such as JAddStringToObject to make it easier to create JSON objects and send them to the Notecard.
The development board that comes in a Blues Starter Kit, the Notecarrier F, performs all the necessary wiring so that the Swan can communicate with the Notecard via I2C. The NoteRequest API performs this communication.

With a connection with Notehub established we next need to gather data from the accelerometer. The Zephyr code to take a reading from the LIS3DH is relatively straightforward on its own.

struct sensor_value accelerometerData[3];
int rc = sensor_sample_fetch(sensor);
if (rc != 0) {
    printk("Failed to fetch sensor data (error: %d)\n", rc);
    continue;
}

rc = sensor_channel_get(sensor, SENSOR_CHAN_ACCEL_XYZ, accelerometerData);
if (rc != 0) {
    printk("Failed to get sensor data (error: %d)\n", rc);
    continue;
}

float x = sensor_value_to_float(&accelerometerData[0]);
float y = sensor_value_to_float(&accelerometerData[1]);
float z = sensor_value_to_float(&accelerometerData[2]);
printk("Reading - x: %f, y: %f, z: %f\n", x, y, z);

This code snippet takes a single accelerometer reading and places the values in three floating point variables named x, y, and z.

For this example we need code that is a little more complex though, as we’re not taking one accelerometer reading—instead, we’re taking a series of readings over a period of time so that it can be sent to an ML model to look for patterns.

For this project we’re using Edge Impulse to create and train our models. After you’ve built a model with Edge Impulse, Edge Impulse lets you download an SDK with sample code that helps you gather sensor data at the intervals their platform expects for training purposes. Here’s what that ends up looking like in our Zephyr code.

struct sensor_value accelerometerData[3];
float *buffer = (float *)malloc(EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE * sizeof(float));

for (size_t ix = 0; ix < (EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE - 2);
    ix += EI_CLASSIFIER_RAW_SAMPLES_PER_FRAME)
{
    // Determine the next tick (and then sleep later)
    uint32_t next_tick_ms = NoteGetMs() + EI_CLASSIFIER_INTERVAL_MS;

    int rc = sensor_sample_fetch(sensor);
    if (rc != 0) {
        printk("Failed to fetch sensor data (error: %d)\n", rc);
        continue;
    }

    rc = sensor_channel_get(sensor, SENSOR_CHAN_ACCEL_XYZ, accelerometerData);
    if (rc != 0) {
        printk("Failed to get sensor data (error: %d)\n", rc);
        continue;
    }

    float x = sensor_value_to_float(&accelerometerData[0]);
    float y = sensor_value_to_float(&accelerometerData[1]);
    float z = sensor_value_to_float(&accelerometerData[2]);
    printk("x: %f, y: %f, z: %f\n", x, y, z);

    buffer[ix] = x;
    buffer[ix + 1] = y;
    buffer[ix + 2] = z;

    int32_t delay_ms = next_tick_ms - NoteGetMs();
    NoteDelayMs(delay_ms < 2 ? delay_ms : 2);
}

The various constants in this sample, EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE, EI_CLASSIFIER_RAW_SAMPLES_PER_FRAME, and EI_CLASSIFIER_INTERVAL_MS, help dictate exactly how often the code takes accelerometer samples and loads them into the buffer. If you run the code and look at the logs you’ll see the accelerometer samples logged live.

With the data loaded into a buffer variable, our firmware’s last task is to send that data to Notehub.

Sending the Data

Large accelerometer samples like we’re using in this project require a decent amount of storage, and historically, working with these larger data packets was problematic for the Notecard, as the Notecard is primarily a low-bandwidth and low-power friendly device.

However, the new Notecard v5.3.1 firmware release includes a new feature aimed at drastically speeding up data transfer for these types of transfers, and allowing you to upload up to 128kb at a time—which is plenty for our situation.

The new Notecard APIs are named card.binary, and the way you use them in Zephyr apps is with the NoteBinaryStoreTransmit and NoteBinaryStoreReceive methods. Here’s what that looks like in our sample.

NoteBinaryStoreTransmit((uint8_t *)buffer,
    (EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE * sizeof(float)),
    (EI_CLASSIFIER_DSP_INPUT_FRAME_SIZE_COBS * sizeof(float)),
    0);

The NoteBinaryStoreTransmit method loads the buffer into a dedicated area of the Notecard’s memory. Once loaded, you can send the data to your Notecard using the Notecard’s web.post method with the binary flag set to true. Here’s what that looks like.

J *req = NoteNewRequest("web.post");
JAddStringToObject(req, "route", "ingest");
JAddStringToObject(req, "content", "binary/octet-stream");
JAddBoolToObject(req, "binary", true);
NoteRequest(req);

At this point our code is now sending batches of accelerometer readings to Notehub as a binary stream of floating-point values. Our final task is to write an endpoint that can accept that stream, parse out the floating-point values, and send them to Edge Impulse as new training data for our ML model.

Getting the Data to Edge Impulse

In this step we’re going to look at how to create an HTTP server that can accept data from Notehub and forward it to Edge Impulse. The example code I’m providing is written in Node.js, Express, and JavaScript, as that’s my toolchain of choice, but the server needed for this step can be written in any language and using any framework you’d like.

As with before, the full source code required to create the server is open source and available on GitHub, and I’ll be highlighting the most important parts here.

At the highest level, this endpoint has to listen for POST requests coming in at the root of the server. Here’s how that’s done in Express.

const express = require("express");
const app = express();

app.post("/", async (req, res) => {
  ...
});

Once you have the request, you next have to parse out the floating-point accelerometer values coming from Notehub. Specifically, the code has to parse the request, get out 32-bit floating point values one at a time, and put them into an array of readings to use later. Here’s what that code looks like in JavaScript.

const binaryFromRequest = Buffer.from(request, "binary");
const dataView = new DataView(binaryFromRequest.buffer);

for (let i = 0; i <= buffer.length - 1; i += 12) {
  let x = dataView.getFloat32(i, true);
  let y = dataView.getFloat32(i + 4, true);
  let z = dataView.getFloat32(i + 8, true);
  data.push([x, y, z]);
}

With the data aggregated, the last step is to get our data to Edge Impulse. For this, Edge Impulse provides an ingestion API that expects data in a given format, and places a new entry in your model’s training set.

Here’s what the code to do that in JavaScript looks like.

const emptySignature = Array(64).fill("0").join("");
const body = {
    protected: {
        ver: "v1",
        alg: "none",
        iat: Math.floor(Date.now() / 1000),
    },
    signature: emptySignature,
    payload: {
        device_name: "device-1",
        device_type: "LIS2HH12",
        interval_ms: 1,
        sensors: [
            { name: "accX", units: "m/s2" },
            { name: "accY", units: "m/s2" },
            { name: "accZ", units: "m/s2" },
        ],
        values: data,
    },
};

try {
    await fetch("https://ingestion.edgeimpulse.com/api/training/data", {
        method: "POST",
        headers: {
            "x-api-key": process.env.EDGE_IMPULSE_API_KEY,
            "x-file-name": "test",
            "x-label": "idle",
            "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
    });
} catch (e) {
    console.log("Error publishing data", e);
}

Now that you have a server you need to make the server available on the public internet. You can do this via your favorite hosting provider, or, if you’re looking for a quick way to test you can use a service like localtunnel or ngrok.

I’m a big fan of ngrok as I’ve found it works well and they have a generous free tier. After installing, you can run ngrok with a simple command from your terminal or command prompt.

ngrok http 3000

Running this command makes the provided port (in this case 3000) available on the public internet at the provided URL.

Once you have this URL your very last step is to create a proxy route in Notehub. The proxy route provides the connection so that Notehub knows to invoke your web server when it receives a web.post request from the Notecard. Here’s an example of the proxy route you need to create, making sure to provide your own URL for the URL field.

And with that—you’re all set. If you start up your firmware on your device it’ll start collecting accelerometer samples. The firmware will then use the Notecard to send your data to Notehub, which invokes your proxy route, which sends the data to Edge Impulse where you can further refine your ML models.

Pretty cool!

The power of this approach is that it can run in any environment that has cellular connectivity. Meaning, you could adapt this code to run on your production hardware, and start collecting training data from devices in real-world conditions.

Exactly how you’ll want to use this code will likely vary. Maybe you’d want to take a few samples a day at different intervals. Maybe you’ll want to create a Notehub environment variable and only send readings when that variable is activated. The idea behind this sample is to you how the raw data transfer works, and to serve as inspiration for the code and techniques you may want to incorporate into your own projects.

And speaking of techniques you may want to incorporate, I have one more fun thing to show you.

Updating ML Models

In this article we’re looking at how to implement a robust MLOps process. In the previous section we saw how to gather training data from devices in the field, which allows you to continuously improve your ML models with real data. But that leaves a big problem—after you’ve done the work to build an improved version of your model, how do you get that model back out to your devices in the field?

The Notecard offers a compelling answer to this question with Notecard Outboard Firmware Update.

What is Notecard Outboard Firmware Update?

Over-the-the firmware updates are table stakes in IoT, but implementing the updates themselves is often a complex and highly risky endeavor. Most firmware-update processes require developers to write code, generally placed within the application itself, or within its RTOS, requiring a special ‘bootloader’ and firmware layout. This requires a high degree of skill, is susceptible to bad updates “bricking” or rendering devices non-functional, and often removes developer choice from the equation.

Outboard Firmware Update is a Notecard feature that allows device builders to implement OTA firmware updates in their devices without writing any code. Additionally, developers have the freedom of choice, and may select from a large number of microcontrollers (MCUs), programming languages, and real-time operating systems (RTOS), and can even perform updates on ‘native’ applications with no code from Blues and no RTOS at all.

Outboard Firmware Update is compelling for machine-learning projects like the one we’re discussing in this article, because it allows you update an app’s full ML model, and it allows you to do so remotely, and all without the risk of bricking your devices.

How does Notecard Outboard Firmware Update work?

The Notecard’s docs have a convenient checklist for everything you need to do to perform an outboard firmware update. Let’s look at how each item in that list works in this project.

You ensure your hardware is using the required wiring.

Because we’re using a Notecarrier F from the Blues Starter Kit for this project, all wiring between the Notecard and our host (the Blues Swan) is already ready to go. If you’re using other boards, see this guide for details on the required wiring.

You enable Notecard Outboard Firmware Update on your Notecard.

We’re performing the necessary call to make this happen in our Zephyr firmware. Specifically, the sample code performs a card.dfu request on the Notecard setting "name" to "stm32" (because the Swan is an STM32-based MCU), and "on" to true.

J *req = NoteNewRequest("card.dfu");
JAddStringToObject(req, "name", "stm32");
JAddBoolToObject(req, "on", true);
NoteRequest(req);

You build your firmware image file.

This step requires you to build the binary firmware image file you’d like to update your device with. In a production workflow, this step would occur after you have an updated version of your model ready, have placed the updated model into your application, and have done the necessary testing to push the model out to some, or all, of your devices.

For local testing, I’d recommend adding a simple logging statement near the top of main() so you can see the firmware update in action.

printk("[INFO] version: 2.0\n");

With the app updated you’ll need to build your Zephyr app, and then grab the built binary in your project from build/zephyr/zephyr.bin.

You upload your firmware on Notehub.

Once you have your new binary visit the Firmware section of your Notehub project, click the Upload firmware button, and upload your newly built file.

At this point Notehub has your firmware and is ready to push it out to your devices. To do so, go to your Notehub project’s Devices page, and then select the Host Firmware tab. Here you’ll see all available firmware versions for your host devices, and hitting Apply starts the process of getting the updated firmware on your host.

The Notecard downloads the firmware, verifies it, and performs the update.

Once you’ve queued up a firmware update in Notehub, the Notecard detects a new host binary is available on its next sync and downloads the firmware into its own flash storage.

The Notecard will then perform a RESET on the host microcontroller, which places it into its ROM bootloader. Then, using a microcontroller-specific communications protocol, the Notecard reprograms the various areas in flash as directed by instructions within the firmware image file, verifies them via MD5 hashes, and restarts the MCU.

The great thing is this all happens automatically, and at the end of the process your device will start running your updated model automatically.

Putting it all together

The big picture is each of the two processes discussed in this article—an easy way to collect ML training data from remote devices, and a workflow to remotely update your models—are both tools that can help you build a more robust MLOps process. The end goal is to avoid shipping your models once and forgetting about them, and to instead establish a process of continuously collecting data, and continuously improving the quality of the models you use for your production apps.

This article’s samples are reference implementations and are both available on GitHub. You may wish to use their code verbatim, or take the bits and pieces that make sense for your project.

At Blues we create a lot of real-world TinyML samples. If you found this discussion interesting, you might want to check out our ML accelerator projects, and the many ML projects our community have built. And if you have any questions about this post, or want to discuss anything further, check out our forum.

When to Use Tadiran (Li-SOCl2) vs Lithium Polymer (LiPo) Batteries in IoT Applications

Rob Lauer — Mon, 10 Jul 2023 17:52:26 +0000

As a product designer or embedded engineer, selecting the appropriate battery technology is crucial for ensuring the best performance/longevity combination to power your embedded device or IoT application.

In this article, we will perform a high-level comparison of Tadiran (i.e. Li-SOCl2) batteries and Lithium Polymer (LiPo) batteries, helping you to decide which is best suited for your deployment scenario.

Specifically, we will answer the following questions:

What are Tadiran Li-SOCl2 batteries?
What are LiPo batteries?
What are the optimal temperature ranges for Tadiran and LiPo batteries?
What are the self-discharge rates of Tadiran and LiPo batteries?
What are some valid use cases for Tadiran vs LiPo batteries?
And why aren't we talking about alkaline batteries!?

What is a Tadiran Battery?

Tadiran is the brand name of a type of Lithium Thionyl Chloride (Li-SOCl2) battery. Tadiran Li-SOCl2 batteries are known for their long shelf-life (up to 40 years in optimal conditions), relatively high voltage (3.6V), low self-discharge rates (~0.7% per year), and the ability to operate in extreme temperature ranges (-80°C to 125°C).

Yes, Tadiran likes to acknowledge these "extreme" capabilities in their marketing materials!

NOTE: While known for their Li-SOCl2 batteries, Tadiran does offer Li-ion batteries as well. However, for the purposes of this article we are going to focus only on their Li-SOCl2 batteries.

While Li-SOCl2 Tadirans are not rechargeable, they are often used in low-power, long-life applications such as remote monitoring systems, smart meters, asset tracking, and IoT deployments in relatively harsh environmental conditions.

How do Li-SOCl2 Tadiran Batteries Work?

Li-SOCl2 battery technology takes advantage of the high reactivity of lithium, the lightest of all metals, and a highly electronegative chlorinated compound, thionyl chloride (SOCl2).

Two types of Li-SOCl2 battery structures. Image credit gebc-energy.com.

In these batteries, lithium serves as the anode, and thionyl chloride serves as the cathode active material. When the battery discharges, the lithium is oxidized, and the thionyl chloride is reduced. The resulting reaction generates a high nominal voltage (again, typically around 3.6V).

Pros and Cons of Li-SOCl2 Tadiran Batteries

Li-SOCl2 Tadirans shine in scenarios where a long shelf-life, low self-discharge rate, high pulses, and ability to function in wildly varying temperature ranges are key requirements. Their high cell voltage also may allow fewer batteries to be used in a series, potentially saving space and reducing complexity in the design of device enclosures.

The Tadiran PlusesPulse series of Li-SOCl2 batteries.

However, Li-SOCl2 batteries are not without their limitations. Since they are not rechargeable, once they are depleted they must be manually replaced. Therefore, they aren't suitable for high-power applications that discharge rapidly, nor in remote scenarios where solar/wind/hydro power is readily available for recharging purposes. Likewise, Tadirans are not inexpensive! Li-SOCl2 Tadiran batteries often cost considerably more than LiPo batteries when comparing $ per amp hour (though the total cost of ownership may vary, depending on the use case).

Common IoT Applications for Li-SOCl2 Tadiran Batteries

Thanks to their unique properties, Li-SOCl2 Tadiran batteries are often found in a variety of IoT deployments, including:

Utility Metering Systems: Gas, water, and electricity metering systems often use Tadirans due to their long operational lifespan and reliability.
Emergency Devices: Devices like fire/smoke detectors and alarm systems often use these batteries due to their long shelf-life.
Edge Computing Devices: Devices deployed in remote or difficult-to-access locations may want to use Tadrian batteries due to their high energy density and long operational life.

When it comes to integrating with the Blues Notecard, this specific Tadiran is ideal for the high current pulses the Notecard requires when used in a region that requires access to a GSM network:

The Blues version of the Tadiran TLP-93111 battery.

NOTE: This battery is based on the Tadiran TLP-93111 and was modified for Blues to include a JST connector so that you can easily use this battery with any of our Notecarriers.

What is a Lithium Polymer (LiPo) Battery?

Lithium Polymer (LiPo) batteries are a type of rechargeable battery that utilize a polymer electrolyte instead of a liquid electrolyte found in other lithium-ion batteries. This unique composition allows LiPo batteries to be lightweight and flexible, making them a popular choice for low-cost powering of embedded/IoT devices, consumer electronics, and devices that require custom battery sizes.

An example LiPo battery.

How do LiPo Batteries Work?

LiPo batteries work on the same fundamental principles as other lithium-ion batteries. They move lithium ions from the negative electrode (anode) to the positive electrode (cathode) during discharge - and move them back while charging. The anode in a LiPo battery is typically made of a type of lithium compound (e.g. lithium cobalt oxide), which can readily give up lithium ions.

LiPo battery structure. Image credit dnkpower.com.

Pros and Cons of LiPo Batteries

Like other lithium-ion batteries, LiPo batteries have a high energy density, meaning they can store a large amount of energy for their size and weight. Unlike Tadiran batteries, LiPo batteries can be recharged hundreds of times, making them a popular choice for many electronics devices. LiPo batteries are also lightweight, can deliver power quickly with high discharge rates, and as mentioned are very flexible in their shape and size.

LiPo batteries can be manufactured in virtually any shape or size. Image credit lipolbattery.com.

LiPo batteries are no silver bullet though - they do have some disadvantages! Care must be taken not to over-charge or over-discharge them, as this can significantly reduce their lifespan, or even cause them to catch fire. But it's important to note that most devices using LiPo batteries include safety circuits to prevent these issues from happening.

Finally, while LiPo batteries can be recharged many times, each charge and discharge cycle slightly reduces their capacity. After numerous cycles, the maximum capacity will be significantly reduced, at which point the battery may need to be replaced.

Common IoT Applications for LiPo Batteries

While there is plenty of overlap between LiPo and Li-SOCl2 Tadiran batteries in terms of use cases, lower-power and more cost-sensitive applications tend to use LiPo battery technology:

Remote Monitoring Systems: Remote systems for weather monitoring, wildlife tracking, and other environmental sensors often use LiPo batteries for their longevity, ability to be recharged, and operation in somewhat unpredictable conditions (but less "extreme" conditions than a Tadiran).
Smart Agriculture: In smart farming, sensors and devices are used for monitoring soil moisture, weather conditions, and livestock tracking. These devices often use LiPo batteries because they can provide low-cost reliable operation for an extended period.
Backing Up Home Automation Devices: Devices like smart locks, security cameras, and other IoT home automation systems are often line-powered, but also utilize LiPo batteries as a backup in case of a power outage.

So...Which Should I Choose?

The answer, as you may expect, is: "it depends on your use case!". Which of the following are most important for your deployment scenario?

Operating Temperature Range

When comparing the operating temperature ranges of Tadiran and LiPo batteries, Tadiran batteries have a clear advantage of -80°C to 125°C. Their Li-SOCl2 chemistry enables them to perform well in extreme temperatures, making them suitable for applications in harsh environments.

While LiPo batteries have a more limited temperature range (-20°C to +60°C) compared to Tadiran batteries, they still offer a wide operating range suitable for many implementations.

✅ Tadiran Li-SOCl2 ⛔️ LiPo

Longevity (Self-Discharge Rate)

The self-discharge rate of a battery refers to the percentage of charge it loses over time when not in use. This is an important factor to consider, especially for applications requiring long periods of inactivity. Tadiran batteries offer an extremely low self-discharge rate (~0.7% per year) while LiPo batteries self-discharge at a rate of up to 5% per month when not in use.

✅ Tadiran Li-SOCl2 ⛔️ LiPo

Flexibility

The unique composition of LiPo batteries allows them to be not only lightweight (which is critical for many solutions) but also flexible and able to be shaped into virtually any size or shape. Tadirans, on the other hand, are limited to very specific shapes (though considering their higher voltages, may consume less physical space in an enclosure depending on the power requirements).

⛔️ Tadiran Li-SOCl2 ✅ LiPo

Cost

Comparing the cost of Tadiran Li-SOCl2 batteries and LiPo batteries can be complex because the true cost of a battery depends on many different factors. You need to factor in its capacity along with recharge cycles/total power delivered, and the specifics by manufacturer/model (not to mention quantity purchased!).

In general, Tadiran Li-SOCl2 batteries are considered "specialty batteries" that aren't as widely available. They tend to be more expensive than LiPo batteries, as they possess the unique properties noted previously. When comparing total energy delivered between Tadiran and LiPo batteries, LiPo tends to come out ahead when it comes to total cost of ownership.

WARNING: Please note that the specifics can vary, and for an accurate and up-to-date comparison, you would need to look at the prices from various suppliers or directly from the manufacturers.

⛔️ Tadiran Li-SOCl2 ✅ LiPo

What about Alkaline Batteries?

Generally speaking, alkalines are the "worst of both worlds" in comparison with LiPo and Tadiran batteries. Aside from their low cost and wide availability, alkalines have a very low energy density (when compared to LiPo and Tadiran). This primarily impacts longevity, as devices won't last as long under comparable usage conditions. Alkalines also perform more poorly at high current-drain rates, aren't rechargeable, and their capacity decreases dramatically in low temperatures.

The venerable Duracell AA alkaline battery. Image credit Duracell.

Conclusion

When choosing between Tadiran Li-SOCl2 and LiPo batteries for an embedded device or IoT application, it is crucial to consider factors such as energy density, operating temperature range, self-discharge rate, and the specific requirements of your application.

Tadiran batteries excel in low-power, long-life applications, and in extreme temperature environments, while LiPo batteries are ideal for lower-cost deployments, scenarios where they may be recharged, and devices requiring custom battery shapes.

If you need help determining the best battery tech for your individual solution, feel free to reach out via the Blues community forum. 🔋

Use Cell Tower and Wi-Fi Triangulation to Achieve Pin-Point Locations, without GPS

Rob Lauer — Thu, 04 Aug 2022 19:00:14 +0000

Many IoT solutions include one basic requirement: to know precisely where they are in the world.

While ascertaining location is usually handled with a GNSS/GPS module, there are scenarios where GPS is not reliable or practical. In fact, I'll give you three exact scenarios:

Indoor deployments where getting a GPS satellite fix is impossible.
Use of a physical enclosure that prevents a GPS fix.
Low-power solutions that can't afford the power drain of GPS.

Here at Blues Wireless, when we talk about gathering lat/lon coordinates, we usually refer people to the onboard GPS capabilities of the Cellular Notecard, which we highly recommend as the first (and often only) way of ascertaining location.

However, today I want to look more closely at a lesser-known capability of the Notecard: Cell Tower and Wi-Fi Triangulation.

Triangulation

If you've taken basic trigonometry or geometry courses, you already know that triangulation is the process of determining a location by forming triangles to the point of interest, from a series of other known points.

The Notecard provides built-in capabilities of utilizing triangulation in a few different ways: cell tower triangulation, Wi-Fi triangulation, or both!

Cell Tower Location

If you're experienced with the Cellular Notecard, you've likely noticed the tower_ parameters that show up in Notehub events:

"tower_when": 1656000634,
"tower_lat": 43.074087500000005,
"tower_lon": -89.44282812499999,
"tower_country": "US",
"tower_location": "Shorewood Hills WI",
"tower_timezone": "America/Chicago",
"tower_id": "310,410,17169,77315594",

The tower_lat and tower_lon values are an approximate location of the single cell tower this Notecard was connected to at the given tower_when timestamp. While this is a nice (rough) location, it's not useful on its own when trying to determine the precise location of a device.

For example, here is the approximate position of the cell tower used in a recent request, relative to my location:

Cell Tower Triangulation

In scenarios where GPS is unusable, performing cell tower triangulation with the Notecard can provide a massive improvement, thanks to the magic of the card.triangulate API.

To enable cell tower triangulation on a Cellular Notecard, simply issue this request:

{
  "req": "card.triangulate",
  "mode": "cell"
}

The next time the Notecard establishes a new session with Notehub, information about every visible cell tower will be uploaded and processed. A new set of location data will appear in every Notehub event, prepended with tri_, like so:

"tri_when": 1656011112,
"tri_lat": 43.07113895,
"tri_lon": -89.43272533,
"tri_location": "Shorewood Hills WI",
"tri_country": "US",
"tri_timezone": "America/Chicago",
"tri_points": 16,

Here is the updated location estimate, based on cell tower triangulation only:

As you can see, the actual location has improved significantly, and will only improve as more cell towers are visible.

NOTE: It's important to know that cell tower triangulation comes with a non-trivial power penalty because the modem scan for nearby cell towers can take almost as long as an entire sync. Triangulation also only occurs during a connection to Notehub and there is no way to "re-triangulate" during a continuous Notehub session.

Wi-Fi Triangulation

If your host MCU has an onboard Wi-Fi module (like the ESP32), you can perform a Wi-Fi access point (AP) scan and send this data to the Notecard to perform Wi-Fi triangulation.

NOTE: Wi-Fi triangulation is an experimental, technical preview feature from Blues Wireless that is free
for use today, but may use Consumption Credits in
the future.

The format of the card.triangulate call is a little different when using Wi-Fi triangulation. Note that you can use cell, wifi, or both with wifi,cell when enabling triangulation.

{
  "req": "card.triangulate",
  "mode": "wifi",
  "text": "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)\n+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)\n+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)\n+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)\n+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\n\n"
}

What's that scary-looking text field? It's a newline-terminated list of Wi-Fi access points that follows a pattern similar to the ESP32's AT+CWLAP command output.

Deriving Access Point Data with Arduino

If you're comfortable issuing AT commands to your host MCU, you can send AT+CWLAP and format the response per the above requirements. However, not many of us are so cozy with AT syntax, which is why we provide the
Notecard Auxiliary Wi-Fi Arduino library
for an easier way of programmatically pulling a list of Wi-Fi access points with
your Wi-Fi enabled host MCU, and sending them to the Notecard in one command:

// Update Notecard Triangulation Data
aux_wifi.updateTriangulationData();

Deriving Access Point Data with CircuitPython

Developing with CircuitPython? Here is an example function that uses the built-in wifi library to gather the same WAP data when used with an ESP32 MCU:

import wifi
import binascii

def get_wifi_access_points():
    """ returns a set of visible access points, corresponds to esp32 AT+CWLAP format """
    # https://docs.espressif.com/projects/esp-at/en/latest/esp32/AT_Command_Set/Wi-Fi_AT_Commands.html#cmd-lap

    all_wifi_aps = ""

    for network in wifi.radio.start_scanning_networks():

        wifi_ap = "+CWLAP:("

        if wifi.AuthMode.ENTERPRISE in network.authmode:
            wifi_ap += "5"
        elif wifi.AuthMode.PSK in network.authmode:
            wifi_ap += "6"
        elif wifi.AuthMode.WPA3 in network.authmode:
            wifi_ap += "6"
        elif wifi.AuthMode.WPA2 in network.authmode:
            wifi_ap += "3"
        elif wifi.AuthMode.WPA in network.authmode:
            wifi_ap += "2"
        elif wifi.AuthMode.WEP in network.authmode:
            wifi_ap += "1"
        else:
            wifi_ap += "0"

        bssid = binascii.hexlify(network.bssid).decode("ascii")
        bssid = ':'.join(bssid[i:i+2] for i in range(0,12,2))

        wifi_ap = wifi_ap + ",\"" + str(network.ssid) + "\"," + str(network.rssi) + ",\"" + bssid + "\"," + str(network.channel) + ")\n"

        all_wifi_aps += wifi_ap

    wifi.radio.stop_scanning_networks()

    return all_wifi_aps

Wi-Fi Triangulation in Action

How different are my results when using Wi-Fi triangulation? Well the only access point my ESP32 was able to find was my own router. However, even with just that one AP, here are the results:

"tri_when": 1656011112,
"tri_lat": 43.07113895,
"tri_lon": -89.43272533,
"tri_location": "Shorewood Hills WI",
"tri_country": "US",
"tri_timezone": "America/Chicago",
"tri_points": 16,

Which becomes amazingly accurate when displayed on a map!

Wi-Fi triangulation becomes even more valuable when you realize the power requirements are minimal, and it adds only 1-2 seconds to the sync time with Notehub.

Be sure to consult the developer documentation on Cell Tower and Wi-Fi Triangulation as there are additional settings in Notehub that you may want to change, depending on how you use triangulation in your solution.

Triangulation with Wi-Fi Notecard

Up until now, all of these instructions have revolved around using the Cellular Notecard. What about if you're using the Wi-Fi Notecard (which doesn't have an onboard GNSS/GPS module)?

Luckily enough, Wi-Fi triangulation is enabled on the Wi-Fi Notecard by default, no configuration changes required!

After setting up a Wi-Fi Notecard, here were the results in a given event:

"tri_when": 47,
"tri_lat": 43.07121864,
"tri_lon": -89.43263674,
"tri_location": "Shorewood Hills WI",
"tri_country": "US",
"tri_timezone": "America/Chicago",
"tri_points": 3,

Which, again, when plotted on a map, comes shockingly close to landing on my location:

Summary

While GPS is the de facto standard for identifying the precise location of an IoT device, and should always be the first option when gathering location data, the Notecard's triangulation capabilities provide options when GPS isn't available.

Happy Mapping with the Notecard and Notehub! 📍🗺

Easiest Way to Add Cellular to an ESP32 IoT Project

Rob Lauer — Mon, 02 May 2022 18:45:55 +0000

I've come to appreciate the ESP32 line of microcontrollers from Espressif Systems, mostly due to a combination of low-cost, low-power, yet solid MCU performance. In particular, the ESP32-based HUZZAH32 Feather from Adafruit is a board you'll routinely see in some tutorials we post on Hackster.

Adafruit HUZZAH32

While Wi-Fi and Bluetooth are integrated into some ESP32 MCUs, adding cellular to the mix broadens the deployment options of any IoT project. Having a combination of connectivity options also enables you to use Wi-Fi when available, but fall back on cellular should Wi-Fi be unavailable or the physical location require it.

Developer-Friendly Cellular with the Notecard

The key to success with cellular IoT connectivity on the ESP32 is a secure and reliable System-on-Module, the Blues Wireless Notecard.

The Notecard is a 30mm x 35mm device-to-cloud data pump. With the included cellular and GPS capabilities (and a Wi-Fi option), the Notecard is an easy choice for securely syncing data with the cloud over a variety of global cellular protocols (specifically Cat-1, LTE-M, and NB-IoT).

And the cost? The Notecard comes prepaid with 10 years of global service and 500MB of data, starting at just $49.

But...what about the M.2 edge connector on the Notecard? How does that connect to an ESP32 microcontroller?

Probably not like this:

Easy Integration Options

Let me introduce you to the Blues Wireless Notecarriers. These are development boards that make it dead simple to connect virtually any MCU or SBC to a Notecard. You place the Notecard into the provided M.2 slot and the Notecarrier exposes all of the pins on the Notecard to the MCU.

Now it gets even easier if you're using a Feather-based ESP32 (like I often do). The Notecarrier-AF (part of the Feather Starter kit) has a Feather-compatible socket so you can insert your MCU directly onto the board, for wire-free connectivity.

The Notecarrier-AF also includes onboard antennas, two Grove I2C ports, and JST connectors for solar and/or LiPo batteries.

Notecard + Notecarrier-AF + ESP32 = ❤️

From Device To Cloud, Securely

A key component of the Notecard's security architecture is that it doesn't live on the public Internet. The Notecard doesn't have a publicly-accessible IP address. You must use a proxy, accessed via private VPN tunnels, to communicate between the Notecard and your cloud application.

This is where the Blues Wireless cloud service Notehub comes into play.

Notehub is a thin cloud service that securely (over TLS) receives, processes, and routes data to your cloud endpoint of choice. This could be a big cloud like AWS, Azure, or Google Cloud - or any IoT-optimized platform like Losant, Datacake, or Ubidots. Your own self-hosted custom RESTful API is fine as well!

As an added bonus, Notehub provides OTA firmware update capabilities along with full device fleet management and cloud-based environment variables for easily sharing data across fleets of Notecards.

When to Use Notecard, and When Not

It's important to note that the cellular Notecard is a low-power, low-bandwidth, and high-latency device. Its design center is focused on sending small packets of data (e.g. accumulated sensor readings, generated ML inferences, and the like) on an occasional cadence to the cloud.

👍 Scenarios when the Notecard makes sense:

Any low-bandwidth transfer of data over Cat-1, LTE-M, or NB-IoT cellular
Low-power edge computing deployments (agriculture, smart meters, environmental monitoring, and so on)
High-latency remote control solutions
When secure and encrypted communications are critical
When turnkey cloud integrations are desired

👎 Scenarios when the Notecard doesn't quite work:

As an "always connected" drop-in replacement for Wi-Fi
When you need sub-millisecond latency
Streaming HD video or high res images

Ready to See How it All Works?

With a Blues Wireless Feather Starter Kit for ESP32 you can follow the remainder of this blog post for a quick and easy getting started experience.

Be sure to browse our full developer site for Notecard datasheets and additional technical information.

After creating a free account at Notehub.io and initializing your first project, copy the provided unique ProductUID from the project and save it for the next step.

Programming ESP32 Firmware

The ESP32 supports commonly used languages like Arduino/C and MicroPython. While I'm an avid Python lover, most ESP32 developers are likely writing Arduino or C/C++, so we'll stick with that path for now.

The API that powers the Notecard is completely JSON-based. So technically speaking, it doesn't matter what programming language you use. We provide SDKs for Arduino, Go, C/C++, and Python and our community has built SDKs for .NET and Rust.

Whichever route you take, open up your preferred IDE and paste in this basic sketch:

// Include the Arduino library for the Notecard
#include <Notecard.h>
#define productUID "com.your-company.your-name:your_project"

Notecard notecard;

void setup() {
  delay(2500);
  Serial.begin(115200);
  notecard.begin();

  J *req = notecard.newRequest("hub.set");
  JAddStringToObject(req, "product", productUID);
  JAddStringToObject(req, "mode", "continuous");
  notecard.sendRequest(req);
}

void loop() {
  J *req = notecard.newRequest("note.add");
  if (req != NULL) {
    JAddStringToObject(req, "file", "sensors.qo");
    JAddBoolToObject(req, "sync", true);

    J *body = JCreateObject();
    if (body != NULL) {
      JAddNumberToObject(body, "temp", 25.6);
      JAddNumberToObject(body, "humidity", 48.2);
      JAddItemToObject(req, "body", body);
    }

    notecard.sendRequest(req);
  }

  delay(15000);
}

What exactly is happening in this sketch?

We are using a hub.set request to associate the Notecard with the Notehub project.
We are sending a JSON object (a Note) with mock temperature and humidity data to the cloud, over cellular.
Wait 15 seconds and do it all again!

You can build and upload this sketch to your ESP32 now, then check your Notehub project to see it in the cloud.

Cellular Data in the Cloud

Once that note.add request is initiated, your Note is queued on the Notecard for syncing with the cloud. Since we are keeping this example simple, we are also using the sync:true option in the note.add request to immediately initiate a cellular connection and send the data to Notehub ASAP.

Go ahead and head back to Notehub.io and take a look at the recently uploaded events in the Event panel for your project:

But we don't want your data to live on Notehub! The most important part of the story is securely routing your data to any cloud endpoint. Take a look at our extensive Routing Tutorials and pick your favorite cloud, such as Ubidots, and create an engaging cloud dashboard to interpret your data:

TIP: Communication with the Notecard is bi-directional in nature. This means the Notecard can also receive data from the cloud. See Inbound Requests & Shared Data Guide for more details.

Next Steps

We've barely even started our journey with cellular IoT and the ESP32! Hopefully you've seen that with minimal hardware and minimal firmware, you can easily add cellular connectivity to a new or existing IoT project.

Looking for some good next steps?

If you haven't already, pick up your own Feather Starter Kit for ESP32.
Next, the real Notecard Quickstart does a MUCH better job getting you started.
Consult the Notecard API reference to get a full grasp of the capabilities of the Notecard.
Check out all the awesome Blues Wireless projects on Hackster for inspiration.

Happy hacking on the ESP32! 👩‍💻

Anti-Theft GPS Tracker and Recovery System

Paige Niedringhaus — Wed, 13 Apr 2022 14:00:21 +0000

The words “asset tracking” typically bring to mind moving dots on a map: cars, trucks, planes, and the like. Things that are supposed to move.

But think about things that shouldn't move, things that, if they are on the move, means something is amiss: historical statues, expensive environmental monitors, high value equipment in storage, or even (believe it or not) beehives.

In this Hackster project, I built a Blues Wireless Notecard-powered anti-theft tracker that integrates with Twilio to send SMS alerts to a user’s phone when motion is detected, complete with last known location coordinates and a simple Google Maps URL link.

At a high level, here’s how it works:

The ultra-low-power cellular Notecard (a mere ~8uA when idle) is configured to act as a GPS device, and only begin taking location readings when motion is detected.
When it’s in motion, it begins taking GPS tagged readings every minute and sending them as JSON data to Notehub - a thin cloud service that securely accepts data from the Notecard.
Notehub immediately transforms the raw JSON with the help of JSONata into a payload of relevant info for Twilio, and routes this data on.
Finally, Twilio forwards this data along to the user’s phone and they receive an alert like the screenshot below, with a clickable Google Maps link. Hopefully speeding up recovery of whatever’s gone missing.

The Twilio alert complete with Notecard name, last seen time and location and Google Maps link.

To see how I built this, view the full tutorial on Hackster, where I detail exactly how to set up the hardware and software that made this anti-theft and recovery device possible.

Low Fi LoJack® with Blues Wireless and React

Paige Niedringhaus — Wed, 23 Feb 2022 22:44:52 +0000

The day after Thanksgiving my parents' car was stolen out of the driveway while we were all inside eating dinner. There was a screech of tires, I went to the door to see about the noise and watched their car heading down the driveway and out of sight at high speed.

We called the police, filed a report, and normally that would have been the end of it. The car didn't have LoJack®, OnStar® or any other built-in GPS tracking systems. It did, however, have a Blues Wireless Notecard and Notecarrier AL attached to a battery in the backseat recording GPS coordinates every 10 minutes.

And so begins the tale of how a hobby React asset tracker dashboard became a low fidelity LoJack® tracking a stolen car in the St. Louis area.

As the situation began to unfold, I started live-tweeting what was happening. If you'd like to see the drama in real-time, you can read this Tweet thread:

// Detect dark theme var iframe = document.getElementById('tweet-1464414605145522179-626'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1464414605145522179&theme=dark" }

Let's Talk About How We Got Here

In my previous blog post, I discussed how Blues Wireless makes getting started with IoT development easier in the same way that Create React App makes spinning up a new React application easier. And that's awesome.

But once that sensor data from an IoT device is flowing in to Blues' Notehub application, that's only half the battle. The other half is getting that data back out of and turning it into something useful in the form of charts and maps.

Luckily, Blues makes that pretty darn easy as well. Not only does the data from sensors come in to Notehub in the form of JSON, Notehub also sends JSON back out to wherever you want.

It can push that data pushed via Notehub routes wherever you want: low code platforms Quibtro or Datacake, or other cloud providers like AWS or Microsoft Azure. Or it can be pulled from Notehub via the Notehub API: this is great for getting up and running quickly, building proof of concept apps before you stand up a third-party database.

Today I'll show you how to take a Notecard and my React-based application and make your own asset tracker dashboard. The app pulls data from Notehub, renders that data in charts and maps, and regularly fetches new data to update the UI. Ready?

Configure your Asset Tracker Hardware

Before we get to the dashboard code itself, let's set up a new Notecard project to generate data for the dashboard.

The asset tracker composed of a Blues Wireless Notecard, Notecarrier AL, and LiPo battery.

IoT Hardware List

Here's the equipment you'll need to make this project happen:

Blues Wireless NB-IoT & LTE-M Notecard Global
Blues Wireless Notecarrier AL with LiPo battery connector
LiPo battery from an IoT supplier like Adafruit (mine is the 3.7v 2500mAh version)

Initial Notecard and Notecarrier AL Configuration

To keep this portion of my post more evergreen, I'm going to point you to the Blues quickstart guide to set up a Notecard, Notecarrier, and Notehub project, and the Blues asset tracking guides for the commands needed to configure a Notecard for GPS location tracking.

In addition to these instructions, there's a few important caveats to make this asset tracker work for our purposes.

When setting the inbound and outbound time periods in your hub.set request, make the time period for each 10 minutes. The reason being, there's no way to force a remote update from Notehub when things like environment variables changes, so if we need the Notecard to read new environment variables shortly after they're added, the sync times between Notehub and the Notecard need to be regular.
In the final config step of card.location.track where we start the tracker running, include the property of: "sync":true. This property means as soon as a new event is acquired by the Notecard (a new GPS location, in this case), the Notecard will sync the event to Notehub instead of waiting for its regularly scheduled outbound time.

If you're curious, here's all of the commands I used to set up my Notecard from start to finish using the built-in web REPL on the Blues Developers site.

{"req":"card.restore","delete":true}
#factory reset card

{"req":"hub.set","product":"com.blues.[NOTEHUB_PROJECT_ID_HERE]","mode":"periodic","outbound":10,"inbound":10}
#attach tracker to Notehub project, set it to periodic mode,
#sync outbound reqs every 10 mins and inbound reqs from Notehub every 10 mins

{"req":"card.location.mode","mode":"periodic","seconds":360}
#tell card how often to get GPS reading and only when motion is detected

{"req":"card.location.track","start":true,"heartbeat":true,"hours":12,"sync":true}
#start tracking, issue heartbeat every 12 hours when no motion detected,
#sync data with Notehub as soon as a tracking event is acquired (this is an important one)

The Asset Tracker Software

This dashboard was a fun challenge to build, and it turned out be much more useful than I could have imagined when it was put to the test in a real-world situation.

Technology Powering the Low Fi LoJack® Tracker App

I chose to build this application using the following technologies:

The React-based framework Next.js for its built-in server-side rendering and API data fetching capabilities
Typescript
React Leaflet and Mapbox for my map component
Recharts for my chart components
React Table for my list of events from Notehub

The Dashboard Look and Feel

Low Fi LoJack® App

When all is said and done, the dashboard looks like this short video above: charts, map and list of events.

Tracker Map

React Leaflet map displaying Notecard GPS coordinates over time.

The map is using the React Leaflet library to map all the coordinates from Notehub, display them on the map as blue circles, draw the lines between each circle, and display a marker with clickable tooltip of last recorded location. Mapbox provides the actual map style displayed in the component.

Tracker Charts

Recharts chart displaying Notecard temperature over time

Recharts is displaying both the temperature of the Notecard and the voltage every time a GPS location reading is taken. It also has tooltips to display relevant information when a user hovers over the chart.

Recharts chart displaying Notecard voltage over time

Tracker Events

React Table list displaying paginated Notecard events over time

For a sanity check as much as anything else, there's an event list in a React Table at the bottom of the application showing a paginated list of all the events the dashboard has pulled from Notehub. It shows when the last event was received and a couple of other pieces of information so it's easy to tell, at a glance, what's going on.

Interesting Notes about How the Dashboard's Built

If you're ready to set up your own asset tracker dashboard, skip to the next section, but if you're interested in some of the challenges I ran into along the way and how I solved for them, read on:

I pulled data via the Notehub API instead of using WebSockets to accept data pushed via Notehub Routes.

Many of the low-code dashboard platforms rely on Notehub's routes to push Notecard events to them, but doing that, there's no way to get historical data from Notehub that occurred before the route was hooked up.

To get my React app up and running and populated with data quickly, I decided to use the Notehub API to fetch events directly from Notehub. The Notehub API requires users to create an authorization token to be passed along with requests, but the process is well documented, as is the API to fetch all events and then filter down to the events I wanted on my end (_track.qo events in this case).

Doing it this way also eliminated my need for a persistence layer of some sort in the form of a database, although for a production ready app I would recommend going this route.

The map component needs server-rendered data. Next.js makes it easy.

Another interesting challenge I ran into is that in order to render all the data points and connecting lines on the map, the data must be fetched at app build time, not after the component's rendered.

At first, I built a simple refreshPage() function to run on an interval and force-refresh a page to server-side render and refetch fresh data from Notehub.

Then I found a better way: incremental static regeneration. ISR allows you to create or update static pages after the site's been built without need to rebuild the entire site. The key is an optional revalidate parameter that tells the getStaticProps() function fetching the data server-side to re-fetch new data on an interval specified in seconds and re-generate the page.

Once I'd figured out how to fetch the data on the server-side and get all the events out of Notehub via the API, it was a simple matter of transforming the data into the shape the app needed to render its various components.

Make the React Dashboard Work for You

Ok, so let's make your own tracker app connected to your own Notecard and Notehub project.

Run Low Fi LoJack® Locally

Download the asset tracker app code

First, go ahead and fork my asset tracker repo in GitHub.

Clone or download it to your local machine.

$ git clone https://github.com/paigen11/react-gps-asset-tracker-dashboard

Install all the project dependencies

Open up your code in your IDE of choice: VSCode, WebStorm, Sublime, Atom, etc.

In a terminal, at the root of the project, run npm install to download all the project's dependencies.

$ npm install

Generate an access token for Notehub

To access the events in Notehub, you'll need to generate an access token. The documentation to generate the token is straightforward. Open a terminal instance and follow the instructions.

$ curl -X POST
-L 'https://api.notefile.net/auth/login'
-d '{"username":"[you@youremail.com]", "password": "[your_password]"}'

Copy this token after it's generated - you'll be putting it into your project shortly.

Create a .env.local file at the root of the project

This .env.local file is how Next.js automatically reads in environment variables used at build time or on the client side. All the variables you'll need are build time variables so none of them need to be prefixed with NEXT_PUBLIC_, which allows for variable access on the client side.

These are the variables you'll need to add to the file:

NOTEHUB_PROJECT_ID=APP_ID_GOES_HERE # get this from Notehub
NOTEHUB_TOKEN=NOTEHUB_GENERATED_TOKEN_GOES_HERE # paste in token generated in previous step
MAPBOX_ACCESS_TOKEN=MAPBOX_ACCESS_TOKEN_GOES_HERE_IF_NOT_USING_MINE # if you have your own Mapbox API token, add it here

Start up the app and see if you're getting data

Once all the local environment variables are set with your Notehub credentials, and the project dependencies have been installed, start the app up locally by typing npm run dev at the root of the project.

$ npm run dev

If everything goes according to plan, when you go to http://localhost:8080 you should see something like the screenshots in this article in your browser.

Deploy Low Fi LoJack® to Netlify

It's cool to have this up and running on your local machine and all, but what about if you want to deploy it somewhere where other people can see it?

The quickest and easiest solution I would recommend is the Netlify platform.

I deployed my own version of this app to Netlify in order to share the map and history with the police detective working to recover the vehicle after it was stolen.

Sign up for a free Netlify account

If you don't already have a Netlify account, sign up for a free one.

Netlify signup options

Grant Netlify access to your GitHub repo

After you've logged in to Netlify, you'll need to follow these instructions to grant Netlify access to your GitHub GPS tracker repo.

Set Netlify environment variables during first deployment

During the very first build and deployment of your repo on Netlify, you'll need to add the environment variables we set locally via our .env.local file via Netlify's build and deploy variables.

After you've selected the repo you want Netlify to build, click the "Advanced Build Settings" button, and add each key-value pair from your .env.local file as a new variable here.

Netlify environment variables added in build process

These variables need to be protected on the server side because they give access to Notehub, your project, etc. and shouldn't be stored in GitHub or anywhere else accessible by the general public.

Beyond these steps, the netlify.toml file in the root of the project handles the rest of the Next.js deployment on Netlify without having to do much else.

[build]
publish = ".next"

[[plugins]]
package = "@netlify/plugin-nextjs"

The secret is the @netlify/plugin-nextjs package - it takes care of all the more complicated parts of deploying a Next.js app so you don't have to.

The Grand Theft Auto Conclusion

For about an hour after the car was stolen we were able to follow it around on my app's map because my asset tracker remained undetected in the backseat. After that, the thieves discovered it and ditched it in a park and a few days later the police retrieved it - the tracker was still transmitting its location every 12 hours even though no new motion was detected.

I want to give a special shout out to my coworker Sean, who jumped on a Slack call 20 minutes after the car was stolen and helped me remotely update the Notecard via Notehub environment variables to take more frequent GPS readings so we could more closely follow the car in real time. I feel fortunate to work with such good people.

By the time the tracker was returned to my parents, I'd already left for my own home, so they mailed it to me, and since it was still operating fine, I was able to track its progress via USPS as it made its way towards me.

The OG asset tracker Notecard on its way back to me via USPS after its harrowing ordeal, still working like a champ

Here's the tracker when it arrived back at my house.

The asset tracker Notecard safely packed in a shipping box full of bubble wrap

Over a month after the car was stolen it was found abandoned in terrible condition in an impound lot: bullet holes in the roof (which ruined the interior), dents and scratches on every outside panel, the stench of marijuana inside, an extra 2,500 miles on the odometer, and that's just what could be seen without checking under the hood.

Hopefully the insurance company will write it off.

Where to go from here

Make and deploy your own asset tracker - from hardware to software it's all available with Blues tech and my dashboard app code. You can even use this discount code to get 20% off your first development kit purchase.

There's also a ton of ways this tracker dashboard could be even better. Improvements could include:

An option to download event data to a spreadsheet for easy sharing
Customizable timeframes via a date picker to see different amounts of events on the map and the charts
Add a cloud database that Notehub can push new events to reducing the amount of direct queries to Notehub

I actually extended this idea into another project where I made an SOS-equipped dashboard during a day-long internal company hackathon.

It follows the same principles as the project here, but includes an "SOS Mode", which updates the Notecard remotely to do more frequent GPS location locks, and displays it on the dashboard with a red colored line.

This SOS asset tracker project changes all connecting lines between points to red when SOS mode is enabled.

What will you follow with your own asset tracker?

LoJack® and OnStar® are registered trademarks of the LoJack Corporation and OnStar, LLC. respectively.

Thermal Image Anomaly Detection with TinyML

Rob Lauer — Wed, 16 Feb 2022 20:55:45 +0000

When I say "anomaly detection" you may imagine an overly complicated process, something exclusive to deep learning algorithms and indecipherable coding. In reality, the concept of uncovering anomalous behavior in a system is really just the act of identifying an unclassified or uncertain state.

In this Hackster project, I created a basic anomaly detection ML model with Edge Impulse that processes thermal images to detect unknown states of thermal readings and relays collected data to the cloud with the Blues Wireless Notecard.

By using the "edge ML" capabilities provided by Edge Impulse, the cellular Notecard device-to-cloud data pump from Blues Wireless, a Raspberry Pi Zero 2 W, and an Ubidots dashboard, I was able to create a simple, low-power, thermal monitoring station with only a small bit of Python coding required 🐍.

Animation of all the recorded thermal images.

Be sure to view the full tutorial on Hackster to see how this project was built from scratch!

Blues Wireless - Just Like React, but For IoT

Paige Niedringhaus — Wed, 02 Feb 2022 21:29:41 +0000

Welcome to the start of a new blog series where I'll attempt to show other people with web development backgrounds (like my own), just how simple Internet of Things (IoT) development can be with the help of the right tools like Blues Wireless.

How, you ask? Why, by using an analogy many web developers are familiar with: comparing the unfamiliar (IoT and hardware) to the familiar (JavaScript and the web).

In this first post I'll be showing how Blues Wireless makes getting started with IoT development easier in the same way that popular JavaScript frameworks, like React, make building websites easier.

Two different pieces of tech, solving for the same sorts of problems

It might not be immediately obvious, but React and Blues Wireless actually have a lot in common.

While neither is absolutely essential to building tech today, there's no reason not to use them: both make the process infinitely easier.

Let's face it, most of the time the hardest part of anything is getting started. Whether it's a blank IDE staring at you as you gaze at your keyboard willing the code to appear, or an IoT-connected device, but no path to get the data from the real world where it originates to your virtual world where it will be useful.

It's the worst, but that's where these two seemingly unrelated pieces of tech converge.

For websites, it's JS frameworks to the rescue

To get you started, JavaScript frameworks like React, Vue, Angular, and Svelte all have simple templates to give devs a starting point and let them get over that first hurdle of getting something, anything in the browser.

Once that's been accomplished, developers are free to focus on the more important (and fun) stuff: solving business problems and building useful tools, and less on if the server's running on the right port, the code's compiling, or they've correctly bound event handlers to clicks in the DOM.

React's quick start template: Create React App. It takes care of the hard stuff so we can get to fun stuff faster.

For IoT, it's Blues Wireless and its device-to-cloud data pump

Blues Wireless does the same thing - just for Internet of Things engineers (and especially the ones who know that where their hardware is going, reliable Internet connectivity is not just not a guarantee - it might not even be an option).

Instead of learning the archaic language of AT commands, negotiating exorbitant fees with cellular companies to transmit data to the cloud, and figuring out how to turn that cryptic cloud data into something useful, Blues takes care of all of that for you.

Just buy a Notecard, attach it to a Notecarrier, issue a few simple JSON commands, and you're ready to roll. It just works.

This is a simple diagram showing the flow of data from a Blues Wireless Notecard in the field to the Blues Wireless Notehub cloud. Again, development made easier.

No Really, Blues Wireless Just Works

If you're like me, you're rolling your eyes right now after that last sentence. I get it - I too, would think what I'm saying is too good to be true. But it's not.

Let me list my lack of IoT qualifications when I joined Blues Wireless. When I started, I:

Did not own a Raspberry Pi,
Did not know what a breadboard was,
Could not write, much less debug, Arduino code.

After working at Blues Wireless for close to 4 months, I still can't write or debug Arduino code.

Yet despite this, within 6 weeks of starting, I built a fully-functional asset tracker.

This little guy collects GPS and temperature data, sends that data to the Blues Wireless cloud Notehub, and Notehub pumps that data to the low-code IoT platform Datacake where it decodes the data and displays it.

With the help of the detailed asset tracking documentation on the Blues developer site, in less than 30 minutes, I'd configured a Notecarrier-AF, equipped it with a Notecard to record its GPS coordinates, temperature, and motion data at an interval of once an hour, and pumped that data, in an easy-to-understand JSON data object, to a project I'd set up in the Blues Notehub cloud.

Behold, my asset tracker in all its glory: a Notecard, Notecarrier and LiPo battery

This is the Notehub dashboard. The "Asset Tracker" project in the center is where all my sensor data was sent to.

In another 30 minutes, I had my data in Notehub being sent to the Datacake platform, still in readable JSON format, and being interpreted to display the relevant GPS coordinates on a map.

These are two of the widgets I put on my Datacake dashboard: the map plotting my course over time, and the temperature tracker.

Some of the fields I was setting from the JSON being delivered to Datacake via Notehub.

The Datacake HTTP payload decoder which took in the raw JSON from Notehub and assigned the correct pieces of info to the fields I'd defined in the image above.

The single URL link I added to my Notehub project so it knew which data files to send to my Datacake dashboard.

The best part about all this? Notehub doesn't just work with Datacake.

It works with (and has documentation to connect to) all the most popular cloud platforms:

Plus lots of low-code IoT platforms too:

Once that sensor data is in Notehub, it's simple to send it anywhere else. And once it's anywhere else, just hook into that platform like you would with any other third-party API service providing data. Easy peasy.

Just look at all the possible cloud providers Blues Wireless has provided routing tutorials for to get the data out of Notehub and to your app.

How does this relate to React, Again?

I'll admit, this post is much more about the IoT side of things than in depth look at web development, but I'm operating under the assumption that if you're reading this, you're already fairly familiar with JavaScript, React and the web development world.

What I'm trying to do is connect the dots: React makes web development easier, and Blues Wireless makes IoT development easier.

Could I have set up this neat little asset tracker myself without Blues Wireless? Yes, probably.

Would it have taken me an exponentially longer time, and probably turned into such a frustrating, landmine-strewn obstacle course that I very well might have quit before achieving my goal? Also yes, quite likely.

Just like with JavaScript, I could spend a lot of time on the unfun, nitty gritty details that JS frameworks take care of for me, but why would I? Why spend time and energy on things already solved for in these frameworks, when I could spend that same time building cool, useful stuff instead?

And the same can now be said of IoT prototyping and development. Spend time on the low-level details, or choose Blues Wireless solutions and get to building the "cool, useful stuff" a whole lot sooner.

I'm sold. Are you?

Where to go from Here

If you're ready to get started with your own IoT project, I recommend you check out our Getting Started documentation on our developer experience site. It's what I used to get up and running with my project in no time at all.

What's Next?

Stay tuned for the next installment in this series: I plan to show you how to send data from Notehub to a cloud provider and then display it in your own React app with D3. We are developers after all, building cool data visualizations is fun.