Don't see your favorite hardware here? Rest assured the Notecard works with virtually every MCU and SBC available. If you can't figure out how to complete this tutorial let us know in our forum and we can help you out.

Introduction

This tutorial should take approximately 40-50 minutes to complete.

In this tutorial, you'll learn how to take sensor data, queue it on your Notecard, and synchronize it to Blues Notehub. You'll use C/C++ (Arduino/Wiring) running on a Blues Cygnet wired up to Notecarrier F hardware. If you would like to use a different language, board, or Notecarrier, modify the dropdowns at the top of this guide. And if you get stuck at any point, feel free to reach out for help in our community forum.

This tutorial uses mock sensor readings for simplicity, but feel free to hook up a physical sensor of your choice and use that instead. The goal of this tutorial is to demonstrate reusable firmware techniques you can apply to your own Notecard-based projects.

Set up Hardware

First, you'll need to get all of your hardware connected. In order to complete this guide, you'll need the following:

• A Notecard mounted to a Notecarrier F

• A Blues Cygnet

• A USB-C cable

With your hardware in place, complete the following setup steps:

1. Plug your Cygnet into the Feather headers on the Notecarrier F.

2. Attach the Cygnet to your computer with a USB-C cable, using the USB-C port on the Cygnet.

Create a Notehub Project

Now that your hardware is all connected, let's create a new Notehub project to receive sensor readings from your Notecard.

1. Navigate to notehub.io and log in, or create a new account.

2. Click the Create Project button.

3. In the New Project dialog, give your project a name and ProductUID.

   

   note

   The ProductUID must be globally unique, so we recommend a namespaced name like "com.your-company.your-name:your_product".

4. Take note of your ProductUID. This identifier is used by Notehub to associate your Notecard to your project.

   

Write Firmware

For this portion of the guide you'll be writing firmware on your Blues Cygnet that will communicate with the Notecard. You can write the firmware using either PlatformIO (recommended) or Arduino IDE.

Communicating With Your Notecard

With the hardware setup complete, your host and Notecard are now wired for I2C communication.

The easiest way to communicate with a Notecard over I2C is by using one of Notecard's official SDKs. Since this tutorial uses Arduino, let's look at how to install the Arduino SDK, note-arduino.

Install the Notecard Arduino Library

Set Up Your Notecard

1. Now, configure a Serial interface. You'll use this interface to log information later in your code.

   COPY

   #define usbSerial Serial

2. Next, add a definition for your ProductUID using the value you specified when creating your Notehub project.

   COPY

   #define productUID "com.your-company.your-name:your_product"

3. Above the setup() and loop() functions, declare a global object to represent the Notecard.

   COPY

   Notecard notecard;

4. In the setup() function, initialize the usbSerial object and tell the Notecard library to use this serial object for sending debug output.

   COPY

   delay(2500);
   usbSerial.begin(115200);

5. Initialize an instance of the Notecard class and initialize an I2C connection to the Notecard using the notecard.begin() function. Then, use setDebugOutputStream() to link the debug output to usbSerial with the following code:

   COPY

   notecard.begin();
   notecard.setDebugOutputStream(usbSerial);

6. Now, we'll configure the Notecard. Using the hub.set request, we associate this Notecard with the ProductUID of your project and set the Notecard to operate in continuous mode, which indicates that the device should immediately make a connection to Notehub and keep it active.

   COPY

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

   The lines above build up a JSON object by adding two string values for product and mode, and then fires the request off to the Notecard with the sendRequest() function.

Flash Your Firmware

1. If you're NOT using an STLink programmer like the STLINK-V3MINI, before you upload your compiled sketch to the Swan you'll need to enter bootloader mode by pressing and holding the BOOT button, pressing RESET, then releasing both buttons.

   Arduino IDE

   If you're using Arduino IDE, click the Upload button (right arrow icon) to flash the firmware to your device.

   

   PlatformIO

   If you're using PlatformIO, click the Upload button (right arrow icon) at the bottom of the VS Code interface to flash the firmware to your device.

   

View the Serial Log

Now that your firmware is running on your device, you can use a Serial Monitor to view device output. If you are using an STLINK programmer, you will need to connect a second USB cable from your computer directly to your STM32-based host to view serial output.

Complete the instructions below in your preferred IDE.

Read from the sensor

Now that you've configured your Arduino to communicate with the Notecard, let's grab some pseudo sensor readings.

Install the NotecardPseudoSensor Library

To generate mock sensor readings you'll use the NotecardPseudoSensor library.

Complete the instructions below for your preferred IDE.

Gather Sensor Readings

1. Add the following include to the top of your sketch:

   COPY

   #include <NotecardPseudoSensor.h>

2. Next, include the following namespace under your includes.

   COPY

   using namespace blues;

3. After that, create an instance of NotecardPseudoSensor with the line of code below. Place this directly under your existing Notecard notecard statement.

   COPY

   NotecardPseudoSensor sensor(notecard);

4. Finally, place the following code in your loop function, which generates mock temperature and humidity readings, prints them to the console, and then waits 15 seconds before exiting the loop.

   COPY

   float temperature = sensor.temp();
   float humidity = sensor.humidity();
   
   usbSerial.print("Temperature = ");
   usbSerial.print(temperature);
   usbSerial.println(" *C");
   usbSerial.print("Humidity = ");
   usbSerial.print(humidity);
   usbSerial.println(" %");
   
   delay(15000);

5. Upload this code to your Blues Cygnet. Open the Serial Monitor and you'll see temperature and humidity readings every 15 seconds.

   

Send Sensor Readings to the Notecard

Now that we're getting sensor readings, let's send these to our Notecard.

1. To send a sensor reading to the Notecard, we'll need to construct a new JSON request to the note.add API that includes a new Notefile name (sensors.qo), sets the sync field to true to instruct the Notecard to sync to Notehub immediately, and finally, sets the body to the sensor temperature and humidity. Add the following in loop right after the usbSerial commands to print out readings.

   COPY

   {
     J *req = notecard.newRequest("note.add");
     if (req != NULL) {
       JAddStringToObject(req, "file", "sensors.qo");
       JAddBoolToObject(req, "sync", true);
       J *body = JAddObjectToObject(req, "body");
       if (body) {
         JAddNumberToObject(body, "temp", temperature);
         JAddNumberToObject(body, "humidity", humidity);
       }
       notecard.sendRequest(req);
     }
   }

2. Upload this code to your device. After reboot, the Serial monitor will update to display the response from the note.add request (the total number of Notes in the notefile) each time you add a new reading.

   

View Data in Notehub

Once you start capturing readings, your Notecard will initiate a connection to Notehub and will start transferring Notes. Depending on signal strength and coverage in your area, it may take a few minutes for your Notecard to connect to Notehub and transfer data.

1. Return to notehub.io and open your project. You should see your Notecard in the Devices view.

   

2. Now, click on the Events left menu item. Once your sensor Notes start syncing, they'll show up here. You may need to refresh the page to see newly synced Notes.

   

Use Environment Variables

Environment variables are a Notehub state and settings management feature that allow you to set variables in key-value pairs, and intelligently synchronize those values across devices and fleets of devices.

In this section you'll learn how environment variables work by creating a variable that determines how often your firmware should take sensor readings.

Using Environment Variables in Firmware

The Notecard provides a set of requests for working with environment variables. The most common of these requests is env.get, which allows you to retrieve the value of an environment variable.

Complete the steps below to use the env.get request to retrieve and use the reading_interval environment variable.

1. In setup(), adjust your existing hub.set configuration to set the inbound argument to 5. This tells your Notecard to look for inbound changes from Notehub every 5 minutes.

   COPY

   {
     J *req = notecard.newRequest("hub.set");
     if (req != NULL) {
       JAddStringToObject(req, "product", productUID);
       JAddStringToObject(req, "mode", "continuous");
       JAddNumberToObject(req, "inbound", 5); // ADD THIS LINE
       notecard.sendRequest(req);
     }
   }

2. Next, place the following new function at the bottom of your sketch.

   COPY

   // This function assumes you’ll set the reading_interval environment variable to
   // a positive integer. If the variable is not set, set to 0, or set to an invalid
   // type, this function returns a default value of 60.
   int getSensorInterval() {
     int sensorIntervalSeconds = 60;
     J *req = notecard.newRequest("env.get");
     if (req != NULL) {
       JAddStringToObject(req, "name", "reading_interval");
       J* rsp = notecard.requestAndResponse(req);
       int readingIntervalEnvVar = atoi(JGetString(rsp, "text"));
       if (readingIntervalEnvVar > 0) {
         sensorIntervalSeconds = readingIntervalEnvVar;
       }
       notecard.deleteResponse(rsp);
     }
     return sensorIntervalSeconds;
   }

3. Then, add this line after the #include lines at the top of the file.

   COPY

   int getSensorInterval();

4. Next, find the delay(15000) line at the bottom of your loop() function, and replace it with the code below.

   COPY

   int sensorIntervalSeconds = getSensorInterval();
   usbSerial.print("Delaying ");
   usbSerial.print(sensorIntervalSeconds);
   usbSerial.println(" seconds");
   delay(sensorIntervalSeconds * 1000);

   note

   Notecard for LoRa requires a template for each environment variable you use. If you're using a Notecard for LoRa to complete this tutorial, add the code below to your setup() to provide a template for the reading_interval variable.

   COPY

   {
     J *req = notecard.newRequest("env.template");
     if (req != NULL) {
       J *body = JCreateObject();
       if (body != NULL) {
         JAddNumberToObject(body, "reading_interval", 21);
         JAddItemToObject(req, "body", body);
         notecard.sendRequest(req);
       }
     }
   }

With this code in place, your firmware now uses the reading_interval environment variable to determine how many seconds to delay in between sensor readings. If you flash this updated code to your device and open your serial monitor, you can see the device using the default value for reading_interval of 60 seconds.

Setting an Environment Variable

Now we have our device programmed to retrieve an Environment Variable from Notehub, we will create that variable. Environment variables can be set in the Notehub UI or through the Notehub API. In this tutorial you'll learn how to set the values through the Notehub UI. If you'd like to instead set environment variables through the Notehub API, refer to environment variable requests in the Project API.

1. Return to your Notehub project, go the the Devices page, and double click your device. You should see a screen that looks like this.

   

2. Click the Environment tab.

3. Under the Device environment variables header, define a new environment variable named reading_interval and set its value to 30.

   

Now that you have an environment variable set, you'll see it reflected on your device after your configured inbound interval has passed.

And with that, you've used your first environment variable on your Notecard! To see the real power of environment variables in action, try returning to Notehub and updating your device's reading_interval with your serial monitor open.

Next Steps

Congratulations! You've successfully connected your Blues Cygnet to your Notecard and built a basic IoT project.

If you're following the Cell+WiFi Quickstart, next we recommend learning how to send (and visualize) your data in a cloud application:

1. Use the Notecard to Send Data
2. Set Up Your Microcontroller
3. Build Your First IoT App With Blues
4. Send Data to Your Cloud

At any time, if you find yourself stuck, please reach out on the community forum.