Collecting Sensor Data
CircuitPython, Blues Swan, and Notecarrier F
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 readings from a Device and send readings to your Notecard and the Blues Notehub. You'll use CircuitPython running on a Blues Swan 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, the full source code for each example is available on GitHub.
The tutorial uses mock sensor readings for simplicity, but feel free to hook up a physical sensor of your choice and use that instead.
Set up Hardware
First, you'll need to get all of your hardware connected. Follow the instructions below to connect your Blues Swan and Notecard mounted on a Notecarrier F.
In order to complete this guide, you'll need the following:
- A Notecard mounted to a Notecarrier F
- A text editor or IDE that works well with CircuitPython, like Mu or Visual Studio Code
- A Micro USB to USB-A cable
Connect the MCU to the Notecarrier
-
Plug your Swan into the Feather headers on the Notecarrier F.
-
Attach the Swan to your computer with a Micro USB to USB-A cable, using the Micro USB port on the Swan.
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
"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.
Write Firmware
Now you're ready to write some firmware. When communicating with the Notecard,
you can manually send requests using the Serial write
function and passing-in
JSON objects, or use the note-python
library (the recommended path).
The rest of this tutorial assumes you have already burned the bootloader and flashed the CircuitPython binary to your MCU.
If you haven't, please follow our guide on setting up CircuitPython on the Swan before continuing.
Configure your Notecard
Install the Notecard Python Library
-
To use the
note-python
library, you'll first need to download or clone it from the GitHub repo.
-
Unzip the archive and copy the
notecard
directory into thelib
directory of yourCIRCUITPY
mount.
-
Add an
import
for the library at the top of yourcode.py
file.import notecard
Set up Your Notecard
-
Add some additional imports to the top of your
code.py
file:import board import busio import time import json
-
Add a definition for your ProductUID using the value you specified when creating your Notehub project.
productUID = "com.your-company.your-name:your_product"
-
Configure the I2C Bus and connection to your Notecard, and initialize the connection to the Notecard using the
OpenI2C
function. Be sure to set thedebug
parameter toTrue
to see Notecard requests and responses.port = busio.I2C(board.SCL, board.SDA) card = notecard.OpenI2C(port, 0, 0, debug = True)
-
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.req = {"req": "hub.set"} req["product"] = productUID req["mode"] = "continuous" rsp = card.Transaction(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
Transaction
function.
-
Save the
code.py
file to flash this code to your device. -
Using your IDE or tool of choice, open a Serial monitor to your CircuitPython device. 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:
{}
.
Read from the Sensor
Now that you've configured your MCU to communicate with the Notecard, let's grab
some pseudo sensor readings, where the temperature
comes from the onboard
temperature sensor of the Notecard and the humidity
is a random number.
If you have your own sensor, feel free to hook it up and use your own values instead of this tutorial's mocked ones.
-
To generate psuedo sensor readings you'll use the
notecard-pseudo-sensor
library. Start by downloading or cloning the library from its GitHub repo.
-
Next, unzip the archive and copy the
notecard_pseudo_library
directory into thelib
directory of theCIRCUITPY
mount.
-
Add an import for the library at the top of your
code.py
file.import notecard_pseudo_sensor
-
Configure the pseudo sensor with a reference to the Notecard you created earlier.
sensor = notecard_pseudo_sensor.NotecardPseudoSensor(card)
-
Add the following code block to the bottom of your
code.py
file. This takes a mock temperature and humidity reading before sleeping for 15 seconds and repeating the process.while True: temp = sensor.temp() humidity = sensor.humidity() print("\nTemperature: %0.1f C" % temp) print("Humidity: %0.1f %%" % humidity) time.sleep(15)
-
Save
code.py
and reopen the Serial monitor. Every 15 seconds, you'll see new readings.
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 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 inwhile
loop right after theprint
commands to print out readings.req = {"req": "note.add"} req["file"] = "sensors.qo" req["sync"] = True req["body"] = { "temp": temp, "humidity": humidity} rsp = card.Transaction(req) print(rsp)
-
Save this code to your device. After restart, 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.
If you are curious about how to interact with the Notecard using Python without
the note-python
library. We have provided
a sample script
for review.
You may also be interested in reviewing the Notecard Guide, Notecard Communication Without a Library.
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.
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.
-
First, adjust your existing
hub.set
configuration to set thesync
argument totrue
. Whensync
istrue
, the Notecard synchronizes inbound environment variable changes as soon as they're made in Notehub.req = {"req": "hub.set"} req["product"] = productUID req["mode"] = "continuous" req["sync"] = True # add this line rsp = card.Transaction(req)
-
Next, place the following new function before the existing
while True
loop.# 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. def get_sensor_interval(): sensor_interval_seconds = 60 req = {"req": "env.get"} req["name"] = "reading_interval" rsp = card.Transaction(req) if rsp and rsp["text"] and int(rsp["text"]) > 0: sensor_interval_seconds = int(rsp["text"]) return sensor_interval_seconds
-
Finally, find the existing
time.sleep(15)
line in yourwhile True
loop, and replace it with the code below.sensor_interval_seconds = get_sensor_interval() print(f"Delaying {sensor_interval_seconds} seconds") time.sleep(sensor_interval_seconds)
Your firmware now uses the reading_interval
environment variable to determine how
many seconds to delay in between sensor readings.
If you save this code, after restart you should see your device using
the default reading_interval
value 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.
-
Return to your Notehub project, go the the Devices page, and double click your device. You should see a screen that looks like this.
-
Click the Environment tab.
-
Under the Device environment variables header, define a new environment variable named
reading_interval
and set its value to30
.
Now that you have an environment variable set you should see it immediately reflected on your device.
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. Your
firmware will retrieve the updated value and start using it immediately.
This tutorial had you use several configuration settings that are best used when you have your Notecard connected to mains power.
-
In the
hub.set
request, settingmode
to"continuous"
tells the Notecard to maintain an active network connection. -
In the
hub.set
request, settingsync
totrue
tells the Notecard to immediately synchronize inbound Notes and environment variables from Notehub. -
In the
note.add
request, settingsync
totrue
tells the Notecard to immediately synchronize all outbound Notes to Notehub.
Because each of these settings cause the Notecard to use more power, you
may wish to disable them if you plan to transition your project to battery power.
You can run the command below to put your Notecard into periodic
mode with
the sync
argument turned off.
{
"req": "hub.set",
"mode": "periodic",
"sync": false,
"outbound": 60,
"inbound": 120
}
Learn more about optimizing the Notecard for low-power scenarios in Low Power Design.
Next Steps
Congratulations! You've successfully connected your Blues Swan to your Notecard and built a basic IoT project.
If you're following the Blues Quickstart, next we recommend learning how to send (and visualize) your data in a cloud application:
Use the Notecard to Send DataSet Up Your MicrocontrollerBuild Your First IoT App With Blues- Send Data to Your Cloud
At any time, if you find yourself stuck, please reach out on the community forum.