Get started withandand

Sensor Tutorial

Introduction

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 Arduino/Wiring running on a ESP32 wired up to Notecarrier-AL hardware. If you would like to use a different language, board, or Notecarrier, modify the dropdowns at the top of this guide.

note

The images in this guide use the Notecarrier-AL for reference, but this tutorial applies to the Notecarrier-AA and Notecarrier-AE. The Notecarrier-AE does not include pre-soldered female headers at its edge connector, so you'll need to add those headers before continuing.

If you get stuck at any point during this tutorial, the full source for each example is available in the note-tutorials GitHub repo.

Set up Hardware

First, you’ll need to get all of your hardware connected. Follow the instructions below to connect your ESP32, BME680 sensor, and Notecard mounted on a Notecarrier-AL.

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

Notecard mounted to Notecarrier-AL.

Any ESP32-compatible Microcontroller (MCU). We’ll be using the Adafruit HUZZAH32, but any MCU that can be programmed with the Arduino IDE will do.
Micro USB to USB-A cable.
Your sensor of choice. We will be using the Adafruit BME680, 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 MicroUSB connection of your ESP32. 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 Notecard separately through the USB or LiPo connector on the Notecarrier.

Connect the sensor to your ESP32

First, let’s connect the BME680 sensor to your ESP32

Connect the VIN pin from the BME680 Breakout to the 3V pin on your ESP32.
Connect the GND pin from the BME680 Breakout to the GND pin on your ESP32.
Connect the SCK pin from the BME680 Breakout to the I2C SCL pin on your ESP32.
Connect the SDI pin from the BME680 Breakout to the I2C SDA pin on your ESP32.

Connect the ESP32 to your Notecard

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

Connect V+ from the Notecarrier-AL to the USB pin on your ESP32.
Connect GND from the Notecarrier-AL to a GND pin on your ESP32.
Connect TX from the Notecarrier-AL to the RX pin on your ESP32.
Connect RX from the Notecarrier-AL to the TX pin on your ESP32.
Plug the USB cable directly into your ESP32, which will allow you to flash firmware to your device.

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.

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 "org.coca-cola.soda.vending-machine.v2".

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

Write Firmware

Configure the Arduino IDE

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

Once installed, we’ll need to add support for your ESP32 Board.

Configure the Arduino Boards Manager to use the ESP32

Start the Arduino IDE and open the Preferences menu.
Copy the following path https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_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 "esp32" and click the Install button to add ESP32 board support to the Arduino IDE.
Once the installation is complete, click the Close button.
You need to install the SiLabs CP2104 Driver. This driver allows the Arduino IDE to communicate with and flash your ESP32 DevKit over USB. Download the correct driver for your Operating System and run the installer.
Linux note: If your kernel version is greater than or equal to 5, then you do not need to install the driver. If you are unsure, you can check your kernel version by running uname -srm from your terminal application.
Once the installation is complete, plug your Arduino device back in, open the Arduino IDE, select Adafruit ESP32 Feather from the Tools > Board menu, and select the appropriate Port for your device.

Additional Linux Setup

In order to support the ESP32, you will need to install the following packages:

sudo apt update && sudo apt install \
  python-is-python3 \
  python3-serial

warning

The Arduino IDE MUST NOT be installed from the Ubuntu store. Instead, it must be installed from the ZIP file downloaded from the Arduino downloads page._

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

Arduino Sketch

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.

Read from the sensor

Now that you’ve configured your ESP32 to communicate with the Notecard, let’s grab sensor readings from the BME680. First, you’ll need to install a library for use in the Arduino IDE. If you already have the Adafruit BME680 Library installed, then proceed to step 4.

Select the Sketch > Include Library > Manage Libraries… menu.
In the Library Manager window, type "adafruit bme680" in the search box. Click the Install button to install the Adafruit BME680 Library.
You may see a pop-up that additional dependencies need to be installed. If so, click the Install all button. Once the installation completes, click the Close button on the Library Manager window.
Select Sketch > Include Library > Contributed Libraries > Adafruit BME680 Library to add the following includes to your sketch:


#include <bme680.h>
#include <Adafruit_BME680.h>
#include <bme680_defs.h>

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


Adafruit_BME680 bmeSensor;

We will initialize the sensor, log a success or failure message to the debug console, and set the oversampling rates. In setup(), add the following:


if (!bmeSensor.begin()) {
    serialDebug.println("Could not find a valid BME680 sensor...");
    while(false); // halt sketch
} else {
    serialDebug.println("BME680 Connected...");
}
bmeSensor.setTemperatureOversampling(BME680_OS_8X);
bmeSensor.setHumidityOversampling(BME680_OS_2X);

Now let’s take a reading of the temperature and humidity console. In the loop() function, start by calling the BME680 library performReading() method:


if (!bmeSensor.performReading()) {
    serialDebug.println("Failed to obtain a reading...");
    delay(3000); // Allow sensor to reset
    return;
}

Finally, we’ll output the readings to the console and wait for 15 seconds before continuing to loop.


serialDebug.print("Temperature = ");
serialDebug.print(bmeSensor.temperature);
serialDebug.println(" *C");
serialDebug.print("Humidity = ");
serialDebug.print(bmeSensor.humidity);
serialDebug.println(" %");

delay(15000);

Upload this code to your Arduino. Open the Serial Monitor and you’ll see temp 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.

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 start 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 serialDebug commands used to print out the readings.

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.

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.

Congratulations!

You’ve successfully connected your ESP32 and external sensor to your Notecard!

note

During this tutorial, you set your Notecard into continuous mode, which maintains an active cellular 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}