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 Artemis Thing Plus wired up to Sparkfun Qwiic Cellular 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.
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 Artemis Thing Plus and Notecard mounted on a Sparkfun Qwiic Cellular.
In order to complete this guide, you’ll need the following:
- Notecard mounted to Sparkfun Qwiic Cellular Notecarrier.
- Any Arduino-capable Microcontroller (MCU) with a Qwiic connector. We will be using the SparkFun Artemis Thing Plus, but any MCU that can be programmed with the Arduino IDE will do.
- USB-C to USB-A cable.
- 2 Qwiic connector cables.
- Your sensor of choice. We will be using the SparkFun Environmental Combo Breakout because it includes a BME280 , but you're welcome to use any sensor and adapt the code in this guide to read from your sensor instead.
NOTE: For this tutorial, you'll be powering the Notecard through the USB-C connection of your Artemis Thing Plus. Some Arduino-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 Notecard separately through the USB or LiPo connector on the Notecarrier.
First, let's connect Environmental Combo Breakout to your Sparkfun Qwiic Cellular Notecarrier.
Plug one end of the Qwiic connector cable into one of the Qwiic JST terminals on the Environmental Combo Breakout. You can plug the cable into either terminal and the cable can only be plugged in one way.
Plug the other end of the Qwiic connector cable into either of the Qwiic JST terminals on the Sparkfun Qwiic Cellular Notecarrier.
Now, let's connect your Notecarrier using the I2C Qwiic connector.
Plug one end of the Qwiic connector cable into the Qwiic JST terminals on the Artemis Thing Plus. You can plug the cable into either terminal and the cable can only be plugged in one way.
Plug the other end of the Qwiic connector cable into the open Qwiic JST terminal on the Sparkfun Qwiic Cellular Notecarrier.
When powering up, the Notecard requires a small burst of energy, which cannot be adequately supplied via the Qwiic connector. The Notecarrier has both a USB port and JST connector (for a battery) to supply power directly to the Notecard and support this burst.
Now that your hardware is all connected, let’s create a new Notehub project to receive sensor readings from your Notecard.
Navigate to notehub.io and log-in, or create a new account.
Using the New Project card, 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"
.
Take note of your ProductUID. This identifier is used by Notehub to associate your Notecard to your project.
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 Artemis Thing Plus Board.
Start the Arduino IDE and open the Preferences menu.
Copy the following path
https://raw.githubusercontent.com/sparkfun/Arduino_Apollo3/main/package_sparkfun_apollo3_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.Click OK, then open the Boards Manager from the Tools > Board: [board name] > Boards Manager... menu.
Search for "apollo" and click the Install button to add Apollo board support to the Arduino IDE.
Once the installation is complete, click the Close button.
Next, plug your Artemis Thing Plus device back in, open the Arduino IDE, select SparkFun Artemis Thing Plus 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 over I2C, you'll want to use the note-arduino library. The code snippets below provide everything you need to talk to the Notecard over I2C in Arduino.
The SparkFun Qwiic Cellular provides an I2C connection between the Notecard and an MCU host via a built-in Qwiic connector; if you prefer to communicate with the Notecard over a Serial connection, you can use the TX/RX pins on the Qwiic Cellular board.
Install the Notecard Arduino Library
To use the note-arduino library, you'll need to add it to the Arduino IDE.
Click on Tools > Manage Libraries...
Search for "Blues" in the input box and click the "Install" button next to the "Blues Wireless Notecard" result.
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>
Set-up Your Notecard
Now, configure a Serial interface.
Serial
will be used to log information to the Serial terminal of the Arduino IDE.#define usbSerial Serial
Next, add a definition for your ProductUID using the value you specified when creating your Notehub project.
#define productUID "com.your-company.your-name:your_product"
Above the
setup()
andloop()
functions, declare a global object to represent the Notecard.Notecard notecard;
In the
setup()
function, initialize theusbSerial
object and tell the Notecard library to use this serial object for sending debug output.delay(2500); usbSerial.begin(115200);
Initialize an instance of the Notecard class and initialize an I2C connection to the Notecard using the
notecard.begin()
function. Then, usesetDebugOutputStream()
to link the debug output tousbSerial
with the following code:notecard.begin(); Wire.setClock(10000); // Artemis I2C requires "slow mode" for clock stability // https://forum.sparkfun.com/viewtopic.php?t=52301#p214140 notecard.setDebugOutputStream(usbSerial);
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 incontinuous
mode, which indicates that the device should immediately make a connection to Notehub and keep it active.J *req = notecard.newRequest("hub.set"); 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.Open the Arduino Serial Monitor. If everything has been connected and configured properly, you'll see a few debug messages, including the JSON object you sent, as well as the response from the Notecard
{}
Now that you've configured your Artemis Thing Plus to communicate with the Notecard, let's grab sensor readings from the BME280. First, you'll need to install the SparkFun BME280 library for use in the Arduino IDE.
Click on Tools > Manage Libraries...
Search for "SparkFun BME280" in the input box and click the "Install" button next to the "Blues Wireless Notecard" result.
Once the installation completes, add an include for the BME280 library header to the top of your project.
#include <SparkFunBME280.h>
Outside of the
setup
andloop
functions, declare a global object to represent the BME sensor.BME280 bmeSensor;
In
setup
, add the following to initialize the sensor and log a successful connection or failure to the Serial console.if (bmeSensor.beginI2C() == false) { usbSerial.println("Could not find a valid BME280 sensor..."); } else { usbSerial.println("BME280 Connected..."); }
Finally, we'll output the readings to the console and wait for 15 seconds before exiting the loop.
usbSerial.print("Temperature = "); usbSerial.print(bmeSensor.readTempC()); usbSerial.println(" *C"); usbSerial.print("Humidity = "); usbSerial.print(bmeSensor.readFloatHumidity()); usbSerial.println(" %"); delay(15000);
Now that we're getting sensor readings, let's send these to our Notecard.
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 thesync
field to true to instruct the Notecard to sync to Notehub immediately, and finally, sets thebody
to the sensor temperature and humidity. Add the following inloop
right after theusbSerial
commands to print out readings.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", bmeSensor.readTempC()); JAddNumberToObject(body, "humidity", bmeSensor.readFloatHumidity()); JAddItemToObject(req, "body", body); } notecard.sendRequest(req); }
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.
Return to notehub.io and open your project. You should see your notecard in the Devices view.
Now, click on the Events left menu item. Once your sensor Notes start syncing, they’ll show up here.
You’ve successfully connected your Artemis Thing Plus 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.
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
}