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 Python running on a Raspberry Pi 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 Raspberry Pi, 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.
A Raspberry Pi. Any Single-Board Computer with an exposed GPIO connector, along with Pip and Python 3.x.x will do.
Micro USB to USB-A cable.

Your sensor of choice. This tutorial uses the Adafruit BME680, but you’re welcome to use any sensor and adapt the code in this guide to read from your sensor instead.
A breadboard and jumper wires to connect the BME680 and Notecard to your Raspberry Pi.
A text editor for writing a Python script on the Raspberry Pi. For the sake of this tutorial, nano is sufficient and is installed by default on Raspberry Pi OS. For a better experience, you can use VSCode with the "Remote - SSH" and "Python" extensions installed.

warning

Due to the power requirements of the Notecard, some Raspberry Pi 2 and 3 models include a current-limiting fuse that will power-cycle the device when the Notecard's modem is on and transmitting. To avoid these issues, we recommend using only Raspberry Pi 4 devices with the Notecard and a Notecarrier.

Connect the sensor to your Raspberry Pi

First, connect the BME680 sensor to your Raspberry Pi. You can reference this visual guide from Adafruit to see where each breakout pin should be wired into the Raspberry Pi GPIO header.

Connect the VIN pin from the BME680 Breakout to a 3V3 pin on your Raspberry Pi.
Connect the GND pin from the BME680 breakout to a GND pin on your Raspberry Pi.
Connect the SCK pin from the BME680 Breakout to the GPIO3 (SCL) pin on your Raspberry Pi.
Connect the SDI pin from the BME680 Breakout to the GPIO2 (SDA) pin on your Raspberry Pi.

Connect the Pi to your Notecard

Now let’s connect to your Notecard using Serial on your Raspberry Pi. To ensure you are using the correct pins, be sure to reference the Raspberry Pi GPIO Guide when wiring up the Notecarrier-AL to your Raspberry Pi.

Connect the TX pin from the Notecarrier-AL to the GPIO15 (RXD) pin on your Raspberry Pi.
Connect the RX pin from the Notecarrier-AL to the GPIO14 (TXD) pin on your Raspberry Pi.
Connect the GND pin from the Notecarrier-AL to a GND pin on your Raspberry Pi.
Connect the V+ pin from the Notecarrier-AL to a 5V pin on your Raspberry Pi.

And you're done!

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

Now you’re ready to build your app. Before writing code, you’ll need to ssh into your Raspberry PI from a terminal program and configure Serial and I2C communications.

Configure the Raspberry Pi

Configure Serial between Notecarrier-AL and Raspberry Pi

By default, the primary UART of the Raspberry Pi is reserved for the Linux console. To change this so that you can use UART Serial between the Notecard and Raspberry Pi, you can use the raspi-config terminal utility.

From a Pi terminal session, launch the "Raspberry Pi Software Configuration Tool (raspi-config)."

$ sudo raspi-config

In the terminal UI that loads, select Interface Options.
Select P6 Serial Port.
For "Would you like a login shell to be accessible over serial?", select <No>.
For "Would you like the serial port hardware to be enabled?", select <Yes>.
The next screen will confirm your selections and should read, "The serial login shell is disabled" and "The serial interface is enabled." Select <OK>.

Configure I2C between the BME680 and Raspberry Pi

Again, select Interface Options.
Select P5 I2C.
For "Would you like the ARM I2C interface to be enabled?", select <Yes>.
The next screen will confirm your selection, and should read, "The ARM I2C interface is enabled". Select <OK>.
Right arrow twice, and select the <Finish>.
If prompted, "Would you like to reboot now?". Select <Yes>.

Install I2C Helper Tools

Once your Pi comes back online, SSH back into the device.
Install the i2c-tools package, so you can confirm connections to I2C devices.

$ sudo apt-get install -y i2c-tools

Run i2cdetect to ensure the Adafruit BME680 breakout is detected.

$ sudo i2cdetect -y 1

You should see a 77 in the output. This means a device responded at 0x77, which is the default I2C address of the Adafruit BME680.

Install the BME680 Library

The easiest way to work with the Adafruit BME680 Breakout is with the Adafruit Library, which requires a few dependencies. Let’s get those installed first.

Start by installing Python 3 Pip:

$ sudo apt install python3-pip

Use pip3 to install the following dependencies:

$ pip3 install \
  RPI.GPIO \
  python-periphery \
  adafruit-blinka \
  adafruit-circuitpython-bme680

Write Code

If your terminal output looks similar to that above, then you are talking to your Notecard and all of your hardware is configured correctly!

Read from the Sensor

Now that you’ve configured your Raspberry Pi to communicate with the Notecard, let’s grab sensor readings from the BME680.

Start by adding a few more imports to the top of your sensors.py file. These libraries are needed to communicate with the BME680.

import board
import busio
import time
import adafruit_bme680

Configure the I2C connection to your device, and create a new instance of the sensor. Add the following lines to the end of your program:

i2c = busio.I2C(board.SCL, board.SDA)
sensor = adafruit_bme680.Adafruit_BME680_I2C(i2c)

Now let’s take a reading. Add a while True block to the bottom of your sensors.py file. Now the program will take a temperature and humidity reading, and print them to the console before sleeping for 15 seconds and repeating.

while True:
  temp = sensor.temperature
  humidity = sensor.humidity
  print('Temperature: {} degrees C'.format(temp))
  print('Humidity: {}%'.format(humidity))
 
  time.sleep(15)

Save and exit the sensors.py file. From the same directory, use the python3 interpreter to run the program. Only this time, after the Notecard request and response statements, you’ll see the temperature and humidity values logged to the terminal 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 while True: loop, after the print() statements used to print out the readings.

req = {"req": "note.add"}
req["file"] = "sensors.qo"
req["sync"] = True
req["body"] = { "temp": temp, "humidity": humidity }

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 Raspberry Pi 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
}