Rate this page  

Get started with:andand

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.

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

In this tutorial, you'll learn how to take sensor readings from a Device and send readings to your Notecard and the Blues Wireless Notehub. You'll use C/C++ (Arduino/Wiring) running on a Adafruit Feather M4 Express wired up to Notecarrier-A hardware. If you would like to use a different language, board, or Notecarrier, modify the dropdowns at the top of this guide.

The tutorial uses mock sensor readings for simplicity, but feel free to hook up a physical sensor of your choice and use that instead.

note

If you get stuck at any point during this tutorial, the full source for each example is available on GitHub:

First, you’ll need to get all of your hardware connected. Follow the instructions below to connect your Adafruit Feather M4 Express and Notecard mounted on a Notecarrier-A.

In order to complete this guide, you’ll need the following:

  • Notecard mounted to Notecarrier-A.
  • Any Arduino-capable Microcontroller (MCU) with Feather headers. We'll be using the Adafruit Feather M4 Express , but any Feather that can be programmed with the Arduino IDE will do.
  • Micro USB to USB-A cable.
note

For this tutorial, you'll be powering the Notecard through the Micro USB connection of your Adafruit Feather M4 Express. Some Feather-compatible devices cannot handle 2 Amp pulses from the Notecard when connected to GSM, so if you experience resets or other power-related issues, we suggest powering your separately through the USB or LiPo connector on the Notecarrier.

If you need additional help finding the correct I2C, Power, GND, and Serial pins on your Arduino, consult the Arduino documentation for your board of choice. The Arduino Nano 33, for instance, has the pin designations silk-screened on the bottom of the board, which makes it hard to find a pin while plugged into a breadboard. We consulted the pinout diagram here to make sure everything was wired correctly.

Now, let's connect your Notecard using a Serial connection.

  1. Connect V+ from the Notecarrier-A to the USB pin on your Adafruit Feather M4 Express.

  2. Connect GND from the Notecarrier-A to a GND pin on your Adafruit Feather M4 Express.

  3. Connect TX from the Notecarrier-A to the RX pin on your Adafruit Feather M4 Express.

  4. Connect RX from the Notecarrier-A to the TX pin on your Adafruit Feather M4 Express.

    How to connect pins between the Notecarrier and M4 Express

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. Using the New Project card, give your project a name and ProductUID.

    How to create a new Notehub project

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

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

    Where to find your product UID

For this portion of the guide, we'll be using the Arduino IDE, so be sure to install version 2.0+ if you haven't already.

Once installed, we'll need to add support for your Adafruit Feather M4 Express Board.

  1. Start the Arduino IDE and open the Preferences menu.

    The preferences menu in Arduino IDE

  2. Copy the following path https://adafruit.github.io/arduino-board-index/package_adafruit_index.json into the "Additional Board Manager URLs" field. If there's already something in the box, then add a comma to separate the URLs.

    Location of the Additional Board Manager URLs in Arduino IDE

  3. Click OK, then open the Boards Manager from the Tools > Board: [board name] > Boards Manager... menu.

  4. Before installing support for Adafruit SAMD boards (like the Feather M4), you'll need to install Arduino SAMD drivers. Search for "Arduino SAMD" and click the Install button to add Arduino SAMD Boards (32-bits ARM Cortex-M0+) support to the Arduino IDE.

  5. Next, search for "Adafruit SAMD" and click the Install button to add Adafruit SAMD Boards to the Arduino IDE.

  6. Once the installation is complete, click the Close button.

  7. Plug Feather device in, select Adafruit Feather M4 Express (SAMD51) from the Tools > Board menu, and select the appropriate Port for your device.

Great job, now you're ready to write some firmware!

When communicating with the Notecard, you can manually send requests using the Serial.println function and passing-in JSON objects, or use the note-arduino library . Code snippets are provided for both methods, so feel free to use the approach that works best for you.

    warning

    If NOT using a Notecard firmware library, you may unintentionally send requests to the Notecard so fast that you overflow the 1500 byte buffer used to receive data (whether it be I2C, Serial, or UART). The solution is to pause 250 ms after every 250 bytes sent and ensure the total size of each NDJSON object sent is no more than 8KB.

    1. First, let's alias the Serial interfaces at the top of your program in the Arduino IDE. The first, Serial will be used to log information to the Serial Monitor of the Arduino IDE. The second, Serial1 represents the connection between your Arduino and Notecard. Paste the following code at the top of your sketch:

      #define usbSerial Serial
#define txRxPinsSerial Serial1

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

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

    3. In the setup() function, initialize the usbSerial object.

      usbSerial.begin(115200);
while (!usbSerial) {
   ; // wait for serial port to connect. Needed for native USB
}
usbSerial.println("Starting...");

    4. Also in setup, initialize the txRxPinsSerial object, using a baud rate of 9600, and send a newline (\n) to clear out any pending data on the device.

      txRxPinsSerial.begin(9600);
txRxPinsSerial.println("\n");
delay(250);

    5. Now, we'll configure the Notecard. This one-time operation, also belongs in the setup() function. We will use the hub.set request to associate this Notecard with the ProductUID of your project, as well as set the Notecard to operate in continuous mode (which indicates that the device should immediately make a connection to Notehub and keep it active).

      txRxPinsSerial.println("{\"req\":\"hub.set\",\"product\":\"" NOTE_PRODUCT_UID "\",\"mode\":\"continuous\"}");

    6. Finally, we'll add a while loop to setup to read the Notecard's response, and display the result to the Arduino terminal.

      delay(250); // wait for the Notecard to respond
while (txRxPinsSerial.available() > 0) {
    char incomingByte = txRxPinsSerial.read();
    if (incomingByte != '\r' && incomingByte != '\n') {
       usbSerial.print(incomingByte);
    }
}
usbSerial.println();

    7. Now, it's time to watch the logs and validate the firmware. Open the Serial Monitor, by selecting Tools > Serial Monitor from the menu. The default baud rate is 9600 baud, be sure to select 115200 baud from the drop down menu.

    8. Click the upload button (right arrow icon) to save and flash the firmware to your device.

      If you haven't saved your file yet, you will be prompted to do so. Name your sketch (for example, nano-no-library), and click Save. Once your device is flashed and comes back online, check the serial monitor to confirm your Notecard has been properly configured.

      Starting...
{}

    1. To use the note-arduino library , you'll need to add it to the Arduino IDE.

    2. Click on Tools > Manage Libraries...

    3. Search for "Blues" in the input box and click the "Install" button next to the "Blues Wireless Notecard" result.

      Installing the Blues Wireless Notecard library.

    4. Create a new sketch and select the Sketch > Include Library > Contributed Libraries > Blues Wireless Notecard menu option, to add the following include to your sketch:

      #include <Notecard.h>

    1. First, let's alias the Serial interfaces at the top of your program in the Arduino IDE. The first, Serial will be used to log information to the Serial Monitor of the Arduino IDE. The second, Serial1 represents the connection between your Arduino and Notecard. Paste the following code at the top of your sketch:

      #define usbSerial Serial
#define txRxPinsSerial Serial1

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

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

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

      Notecard notecard;

    4. In the setup() function, initialize the usbSerial object.

      usbSerial.begin(115200);
while (!usbSerial) {
    ; // wait for serial port to connect. Needed for native USB
}
usbSerial.println("Starting...");

    5. Next, initialize the serial connection to the Notecard using the begin() function. Then, use setDebugOutputStream() link the debug output to usbSerial with the following code:

      notecard.begin(txRxPinsSerial, 9600);
notecard.setDebugOutputStream(usbSerial);

    6. Now, we'll configure the Notecard. This one-time operation, also belongs in the setup() function. We will use the hub.set request to associate this Notecard with the ProductUID of your project, as well as set the Notecard to operate in continuous mode (indicating the device should immediately make a connection to Notehub and keep it active).

      J *req = notecard.newRequest("hub.set");
if (req != NULL) {
    JAddStringToObject(req, "product", NOTE_PRODUCT_UID);
    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.

    1. Now, it's time to watch the logs and validate the firmware. Open the Serial Monitor, by selecting Tools > Serial Monitor from the menu. The default baud rate is 9600 baud, be sure to select 115200 baud from the drop down menu.

    2. Click the upload button (right arrow icon) to save and flash the firmware to your device.

      If you haven't saved your file yet, you will be prompted to do so. Name your sketch (for example, nano-with-library), and click Save. Once your device is flashed and comes back online, check the serial monitor to confirm your Notecard has been properly configured.

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

    note

    If you have your own sensor, feel free to hook it up and use your own values instead of this tutorial's mocked ones.

    1. To generate mock sensor readings you'll use the note-arduino library and NotecardPseudoSensor library .

    2. Start by clicking on Tools > Manage Libraries... and search for "Blues" in the input box and click the Install button next to the "Blues Wireless Notecard" result.

    3. Then, search for “NotecardPseudoSensor” in the input box and click the Install button next to the “Blues Wireless Notecard Pseudo Sensor” result.

    4. Add the following include lines to the top of your sketch:

      #include <Notecard.h>
#include <NotecardPseudoSensor.h>

    5. Next, include the following namespace under your NotecardPseudoSensor includes.

      using namespace blues;

    6. After that, create an instance of Notecard notecard and NotecardPseudoSensor with the lines of code below.

      Notecard notecard; // required to use NotecardPseudoSensor library
NotecardPseudoSensor sensor(notecard);

    7. Initialize communication with the NotecardPseudoSensor, by adding the following line to setup().

      notecard.begin(txRxPinsSerial);

    8. 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.

      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);

    9. Upload this code to your Adafruit Feather M4 Express. Open the Serial Monitor and you'll see temperature and humidity readings every 15 seconds.

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

    2. Start by clicking on Tools > Manage Libraries...

    3. Then, search for “NotecardPseudoSensor” in the input box and click the Install button next to the “Blues Wireless Notecard Pseudo Sensor” result.

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

      #include <NotecardPseudoSensor.h>

    5. Next, include the following namespace under your NotecardPseudoSensor includes.

      using namespace blues;

    6. After that, create an instance of NotecardPseudoSensor with the lines of code below. Add it right under the Notecard notecard; line of code.

      Notecard notecard;
NotecardPseudoSensor sensor(notecard);

    7. 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.

      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);

    8. Upload this code to your Adafruit Feather M4 Express. Open the Serial Monitor and you'll see temperature and humidity readings every 15 seconds.

    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 sampled temperature and humidity. Add the following to the loop() function, after the usbSerial commands used to print out the readings.

      char json_request[150];
snprintf(json_request, sizeof(json_request),
    "{"
      "\"req\":\"note.add\","
      "\"file\":\"sensors.qo\","
      "\"sync\":true,"
      "\"body\":{"
        "\"temp\":%d.%02d,"
        "\"humidity\":%d.%02d"
      "}"
    "}",
    (int)temperature, abs(((int)(temperature*100.0)%100)),
    (int)humidity, (int)(humidity*100.0)%100
);

    2. Now, send the request to your Notecard and read the result. Add the following code, just before the call to delay:

      txRxPinsSerial.println(json_request);
delay(250); // wait for the Notecard to respond
while (txRxPinsSerial.available() > 0) {
    char incomingByte = txRxPinsSerial.read();
    if (incomingByte != '\r' && incomingByte != '\n') {
        usbSerial.print(incomingByte);
    }
}
usbSerial.println();

    3. Upload the code to your device. After rebooting, 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.

    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 sampled temperature and humidity. Add the following to the loop() function, after the usbSerial commands used to print out the readings.

      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 the code to your device. After rebooting, 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.

    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.

      The new device in Notehub

    2. Now, click on the Events left menu item. Once your sensor Notes start syncing, they’ll show up here.

      The event list in Notehub

    You’ve successfully connected your Adafruit Feather M4 Express and sensor to your Notecard!

    Now you're ready to connect this Notecard project to a cloud application! Take a look at our routing tutorials, which cover a number of popular cloud applications and data visualization tools.

    note

    During this tutorial, you set your Notecard into continuous mode, which maintains an active network connection and enables faster syncs with Notehub. It doesn't have much impact on data usage, but it will draw more power. If you're connected to battery power, or want to transition your project to battery power, then you can put your Notecard into periodic mode with the following request using the in-browser terminal or directly in your firmware.

    {
 "req": "hub.set",
 "mode": "periodic",
 "outbound": 60,
 "inbound": 120
}