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

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 code snippets below show both, so feel free to use the approach that works for you.

note

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 consult Adafruit's guide for Installing CircuitPython .

    1. Open the code.py file in the CIRCUITPY drive mounted to your computer in your text editor of choice.

    2. Remove any code in the file and add some imports to the top:

      import board
import busio
import time
import json

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

      #define productUID "<com.your.product.uid>"

    4. Configure the serial connection to your Notecard, and write a newline to clear its buffer.

      serial = busio.UART(board.TX, board.RX, baudrate=9600)
serial.write(b'\n')

    5. 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 in continuous 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"
serial.write(bytearray(json.dumps(req)))
serial.write(b'\n') # Print the JSON string out to the Serial monitor
print(json.dumps(req))

    6. Finally, we'll add a while loop to read bytes out from the Notecard and display the result to the Arduino terminal.

      data = serial.read(32)
if data is not None:
   data_string = ''.join([chr(b) for b in data])
   print(data_string, end="")
   print("Notecard configured...")
else:
   print('Notecard not connected...')

    7. Save the code.py file, which will reboot your CircuitPython device. Once it's back online, you can open a Serial monitor to your device and you should see a message indicating that you've successfully configured your Notecard.

    Install the Notecard Python Library

    1. To use the note-python library , you'll first need to download or clone it from the GitHub repo .

    2. Unzip the archive and copy the notecard directory into the lib directory of your CIRCUITPY mount.

    3. Add an import for the library at the top of your code.py file.

      import notecard

    Set up Your Notecard

    1. Add some additional imports to the top of your code.py file:
    import board
import busio
import time
import json
    1. Add a definition for your ProductUID using the value you specified when creating your Notehub project.
    #define productUID "<com.your.product.uid>"
    1. Configure the serial connection to your Notecard, and write a newline to clear its buffer.
    serial = busio.UART(board.TX, board.RX, baudrate=9600)
    1. Initialize the serial connection to the Notecard using the OpenSerial function
    card = notecard.OpenSerial(serial)
    1. 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 in continuous 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.

    1. Save the code.py file to flash this code to your device.

    2. 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 {}.

    Now that you've configured your MCU 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. Add the following import for the at the top of your code.py file, which will help you generate mock sensor readings.

        import random

      2. Add the following code block to the bottom of your code.py file. This generates a mock temperature and humidity reading before sleeping for 15 seconds and repeating the process.

        while True:
   temp = round(random.uniform(18, 22), 4)
   humidity = round(random.uniform(45, 50), 4)
   print("\nTemperature: %0.1f C" % temp)
   print("Humidity: %0.1f %%" % humidity)

   time.sleep(15)

      3. Save code.py and reopen the Serial monitor. Every 15 seconds, you'll see new readings.

      1. To generate psuedo sensor readings you'll use the notecard-pseudo-sensor library. Start by downloading or cloning the library from its GitHub repo .

        The location of the download button in GitHub

      2. Next, unzip the archive and copy the notecard_pseudo_library directory into the lib directory of the CIRCUITPY mount.

        How to move the sensor library to the device

      3. Add an import for the library at the top of your code.py file.

        import notecard_pseudo_sensor

      4. Configure the pseudo sensor with a reference to the Notecard you created earlier.

        sensor = notecard_pseudo_sensor.NotecardPseudoSensor(card)

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

      6. Save code.py and reopen the Serial monitor. Every 15 seconds, you'll see new readings.

      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 sensor temperature and humidity. Add the following in your while loop right after the print commands to print out readings.

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

        2. Now, send the request to your Notecard and read the result

          serial.write(bytearray(json.dumps(req)))
serial.write(b'\n')

data = serial.read(255)
if data is not None:
   data_string = ''.join([chr(b) for b in data])
   print(data_string, end="")

        3. Upload this code to your device. After reboot, 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 sensor temperature and humidity. Add the following in while loop right after the print 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)

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

        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
}